The Open API integration in Aries JAX-RS Whiteboard begins by creating a service of type io.swagger.v3.oas.models.OpenAPI
.
e.g. using Declarative Services
@Component(service = OpenAPI.class) public class MyOpenAPI extends OpenAPI { public MyOpenAPI() { super(); info( new Info() .title("My Service") .description("Service REST API") .contact( new Contact() .email("me@me.com") ); } }
The service properties which are currently supported are:
cache.ttl
- Corresponds to the method io.swagger.v3.oas.integration.SwaggerConfiguration.setCacheTTL(Long cacheTTL)
id
- Corresponds to the method io.swagger.v3.oas.integration.SwaggerConfiguration.id(String id)
ignored.routes
- Corresponds to the method io.swagger.v3.oas.integration.SwaggerConfiguration.setIgnoredRoutes(Collection<String> ignoredRoutes)
pretty.print
- Corresponds to the method io.swagger.v3.oas.integration.SwaggerConfiguration.setPrettyPrint(Boolean prettyPrint)
read.all.resources
- Corresponds to the method io.swagger.v3.oas.integration.SwaggerConfiguration.setReadAllResources(Boolean readAllResources)
The following properties are automatically applied when creating the resource from this service instance:
org.apache.aries.jax.rs.whiteboard.application.scoped=true
- indicating that Aries JAX-RS will scope prototype instance to matching applicationsosgi.jaxrs.resource=true
- indicating that the produced service is a JAX-RS resourceFurther service properties that are supplied by the OpenAPI
service will propagate onto the generated resource service supporting various details such as osgi.jaxrs.application.select
, etc.
Once the OpenAPI service is deployed some automatically generated schema metadata should be available at the URL <application.base>/openapi.[json|yaml]
.
Chances are good that at least some of the autogenerated schema information is correct. It is also quite likely that it requires further customization. This is done by using Open API, Swagger or JAX-B annotations on the resources and types provided/supported by the API.
Please review the Swagger annotation documentation for the most up to date details.
However here is a simple example:
@GET @Operation( summary = "Get users", description = "Get list of users" ) public Response getUsers() {..}
The extra information provided by the @Operation
will enhance the generated schema.
For more complex examples of advanced schema definitions take a look at the resources in integrations/rest-management/rest-management/src/main/java/org/apache/aries/jax/rs/rest/management/internal.