The CXF OpenApiFeature allows you to generate OpenAPI v3.0 documents from JAX-RS service endpoints with a simple configuration. This feature can be configured programmatically in Java or using Spring or Blueprint beans.
<dependency>
<groupId>org.apache.cxf</groupId>
<artifactId>cxf-rt-rs-service-description-openapi-v3</artifactId>
<version>3.2.4</version>
</dependency> |
The cxf-rt-rs-service-description-openapi-v3 is only available in 3.2.x and above due to Java 8 baseline. For older releases, as well as for the users of older Swagger specifications 1.x/2.x, the is dedicated converter provided: org.apache.cxf.jaxrs.swagger.openapi.SwaggerToOpenApiConversionFilter.
The following optional parameters can be configured in OpenApiFeature. Note that although there are some similarities with Swagger specifications 1.x/2.x, OpenAPI v3.0 is a significant revamp of the specification (in a good sense of it).
| Name | Description | Default value (if applicable) | Sample value (if applicable) |
|---|---|---|---|
| securityDefinitions | a list of security definitions* | null | ["basicAuth" -> new SecurityScheme().type(Type.HTTP))] |
| customizer | the customizer class instance | null | new OpenApiCustomizer() |
| swaggerUiMavenGroupAndArtifact | the Maven artifacts to pinpoint SwaggerUI | null | "org.webjars.swagger-ui' |
| swaggerUiVersion | the version of SwaggerUI | null | "3.13.0" |
| supportSwaggerUi | turns on/off SwaggerUI support | false | false |
| filterClass | a security filter** | null | "com.example.filter.SampleFilter" |
| resourceClasses | a list of resource classes which must be scanned** | null | ["com.example.rest.SampleResource"] |
| resourcePackages | a list of package names where resources must be scanned** | null | ["com.example.rest"] |
| ignoredRoutes | excludes specific paths when scanning all resources (see scanAllResources)** | null | ["/api/test"] |
| prettyPrint | when generating openapi.json, pretty-print the JSON document** | true | true |
| runAsFilter | runs the feature as a filter | false | false |
| scan | Scan all JAX-RS resources automatically | true | true |
| readAllResources | Read all operations also with no @Operation** | true | true |
| termsOfServiceUrl | the terms of service URL* | null | null |
| licenseUrl | the license URL* | null | "http://www.apache.org/licenses/LICENSE-2.0.html" |
| license | the license* | null | "Apache 2.0 License" |
| contactUrl | the contact link* | null | null |
| contactEmail | the contact email* | null | "users@cxf.apache.org" |
| contactName | the contact name* | null | null |
| description | the description* | null | "The Sample REST Application with OpenAPI integration" |
| title | the title* | null | "Sample REST Application" |
| version | the version* | null | "1.0.0" |
* - the properties are defined in the OpenAPI class
** - the properties are defined in the SwaggerConfiguration class