The CXF Swagger2Feature allows you to generate Swagger 2.0 documents from JAX-RS service endpoints with a simple configuration.
For generating Swagger 1.2 documents, you can use SwaggerFeature instead of Swagger2Feature (for CXF versions <= 3.1.x).
These features can be configured programatically in Java or using Spring or Blueprint beans.
Note that a cxf-rt-rs-service-description needs to be used if older CXF 3.1.x versions are used.
The following optional parameters can be configured in Swagger2Feature
Note some properties listed below are not available or used differently in SwaggerFeature, as the corresponding properties are used differently in Swagger 2.0 and Swagger 1.2. Please refer to the corresponding Swagger documentation for more information.)
|basePath||the context root path+||null|
|contact||the contact information+||"email@example.com"|
|description||the description+||"The Application"|
|filterClass||a security filter+||null|
|host||the host and port+||null|
|ignoreRoutes||excludes specific paths when scanning all resources (see scanAllResources)++||null|
|license||the license+||"Apache 2.0 License"|
|licenceUrl||the license URL+||""|
|prettyPrint||when generating swagger.json, pretty-print the json document+||false|
|resourcePackage||a list of comma separated package names where resources must be scanned+||a list of service classes configured at the endpoint|
|runAsFilter||runs the feature as a filter||false|
|scan||generates the swagger documentation+||true|
|scanAllResources||scans all resources including non-annotated JAX-RS resources++||false|
|schemes||the protocol schemes+||null|
|termsOfServiceUrl||the terms of service URL+||null|
|title||the title+||"Sample REST Application"|
Note: those descriptions marked with + correspond to the properties defined in Swagger's BeanConfig, and those marked with ++ correspond to the properties defined in Swagger's ReaderConfig.
Configuring from Code
Configuring in Spring
Configuring in Blueprint
Configuring in CXFNonSpringJaxrsServlet
New: Configuring from Properties file
Starting from CXF 3.1.13 and 3.2.0 it is possible to configure Swagger2Feature with a Properties file.
Default location for a properties file is "/swagger.properties". Swagger2Feature will pick it up if it is available, and the location can be overridden with a new Swagger2Feature 'swaggerPropertiesLocation' property.
Note that the properties, if available, do not override the properties which may have been set as suggested above from the code or Spring/Blueprint contexts or web.xml. Instead they complement and serve as the default configuration properties: for example, if some properties have been set from the code then the values for the same properties found in the properties file will not be used.
Enabling in Spring Boot
Accessing Swagger Documents
When Swagger is enabled by Swagger feature, the Swagger documents will be available at the location URL constructed of the service endpoint location followed by /swagger.json or /swagger.yaml.
For example, lets assume a JAX-RS endpoint is published at 'http://host:port/context/services/' where 'context' is a web application context, "/services" is a servlet URL. In this case its Swagger documents are available at 'http://host:port/context/services/swagger.json' and 'http://host:port/context/services/swagger.yaml'.
Starting from CXF 3.1.7 the CXF Services page will link to Swagger documents if Swagger2Feature is active.
In the above example, go to 'http://host:port/context/services/services' and follow a Swagger link which will return a Swagger JSON document.
If CORS support is needed to access the definition from a Swagger UI on another host, the CrossOriginResourceSharingFilter from cxf-rt-rs-security-cors can be added.
Enabling Swagger UI
First one needs to add the following
The newest version 3.x of swagger-ui can also be used.
Automatic UI Activation
This feature is available starting from CXF 3.1.7: Adding a Swagger UI Maven dependency is all what is needed to start accessing Swagger documents with the help of Swagger UI.
For example, lets 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=/swagger.json' which will return a Swagger UI page.
CXF Services page will also link to Swagger UI. Go to 'http://host:port/context/services/services' and follow a Swagger link which will return a Swagger UI page.
Note that CXF OSGI endpoints can only depend on this feature starting from CXF 3.1.8.
Unpacking Swagger UI resources
In CXF 3.1.8: set Swagger2Feature 'supportSwaggerUi' property to 'false' to disable the automatic UI activation described in the previous section
Set a CXFServlet init parameter 'use-x-forwarded-headers' to 'true' if you access Swagger JSON and/or UI via the reverse proxy. If you use CXF SpringBoot starters then this property is prefixed with a "cxf.servlet.init.", "cxf.servlet.init.use-x-forwarded-headers".
You may also need to set Swagger2Feature 'usePathBasedConfig' property to 'true' to prevent Swagger from caching the 'basePath' value.
Set a CXFServlet init parameter 'use-x-forwarded-headers' to 'true' if you access Swagger JSON and/o
CXF's distribution contains the following samples.
- samples/jax_rs/description_swagger: Swagger 1.2 sample using SwaggerFeature programatically
- samples/jax_rs/description_swagger2: Swagger 2.0 standalone sample using Swagger2Feature programatically
- samples/jax_rs/description_swagger2_spring: Swagger 2.0 standalone sample using Swagger2Feature using Spring
- samples/jax_rs/description_swagger2_web: Swagger 2.0 web application sample using Swagger2Feature using Spring
- samples/jax_rs/description_swagger2_osgi: Swagger 2.0 OSGi application sample using Swagger2Feature using Blueprint