DUE TO SPAM, SIGN-UP IS DISABLED. Goto Selfserve wiki signup and request an account.
...
| Name | Description | Default value (if applicable) | Sample value (if applicable) | ||
|---|---|---|---|---|---|
| configLocation | the OpenAPI configuration location | null | /config/openapi-configuration.yml | ||
| scanKnownConfigLocations | scan known OpenAPI configuration location (classpath or filesystem), which are:
| true | true | ||
| propertiesLocation | the properties file location | /swagger.properties | /swagger.properties | ||
| 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 | null (== true) | true | ||
| 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" | ||
| swaggerUiConfig | Swagger UI configuration | null | new SwaggerUiConfig().url("/openapi.json") | ||
| useContextBasedConfig | If set, the unique Context Id is going to be generated for each OpenApiContext instance (see please Using Multiple Server Endpoints). Also, you very likely may want to set scan property to false. | false | false |
* - the properties are defined in the OpenAPI class
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
<dependency>
<groupId>org.webjars</groupId>
<artifactId>swagger-ui</artifactId>
<version>3.13.0</version>
</dependency> |
For example, let's assume a JAX-RS endpoint is published at 'http://host:port/context/services/'.
Open the browser and go to 'http://host:port/context/services/api-docs/?url=/openapi.json' which will return a Swagger UI page.
CXF Services page will also link to Swagger UI. Go to 'http://host:port/context/services/' and follow a Swagger link which will return a Swagger UI page.
See samples/jax_rs/description_openapi_v3 as an example.
To deactivate automatic Swagger UI integration please set 'supportSwaggerUi' property to "false".
Configuring Swagger UI (3.2.7+)
The OpenApiFeature has a way to pre-configure certain Swagger UI parameters (https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md) through SwaggerUiConfig. Theway it is implemented is by passing those parameters as a query string so the Swagger UI could adjust itself.
| Anchor | ||||
|---|---|---|---|---|
|
Samples
CXF's distribution contains the following samples.
Quite often there are more than one JAXRSServerFactoryBean configured within same Apache CXF application, for example, under "/admin" and "/public" endpoints. The older Swagger/OpenAPI v2.0 integrations used such basePath to disambiguate multiple API documentation contexts, but since OpenAPI v3.0 Specification does not explicitly include the concept of basePath anymore, this approach is not working. Luckily, starting from 2.0.6 release, Swagger OpenAPI implementation properly supports Context Id. To activate it from OpenApiFeature, it is enough to set useContextBasedConfig property to true (very likely you would also want to set scan to false).
| Code Block |
|---|
final OpenApiFeature feature = new OpenApiFeature();
feature.setScan(false);
feature.setUseContextBasedConfig(true);
... |
With that, each OpenApiFeature will generate unique Context Id and won't see any classes / packages beyond its own configuration.
Samples
CXF's distribution contains the following samples.
- samples/jax_rs/description_samples/jax_rs/description_openapi_v3: the OpenAPI v3.0 standalone sample using OpenApiFeature programmatically
- samples/jax_rs/description_openapi_v3_osgi: the OpenAPI v3.0 OSGi application sample using OpenApiFeature using Blueprint
- samples/jax_rs/description_openapi_v3_web: the OpenAPI v3.0 sample using OpenApiFeature inside WAR-based deployment
- samples/jax_rs/description_openapi_v3_spring: the OpenAPI v3.0 sample using Spring and multiple context paths / OpenApiFeatures