Swagger2Feature
Table of Contents |
---|
The CXF Swagger2Feature allows you to generate Swagger 2.0 documents from JAX-RS service endpoints with a simple configuration.
...
Note that a cxf-rt-rs-service-description needs to be used if older CXF 3.1.x versions are used.
Properties
The following optional parameters can be configured in Swagger2Feature
...
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
Code Block | ||||
---|---|---|---|---|
| ||||
import org.apache.cxf.frontend.ServerFactoryBean; import org.apache.cxf.jaxrs.swagger.Swagger2Feature; ... Swagger2Feature feature = new Swagger2Feature(); // customize some of the properties feature.setBasePath("/api"); // add this feature to the endpoint (e.g., to ServerFactoryBean's features) ServerFactoryBean sfb = new ServerFactoryBean(); sfb.getFeatures().add(feature); |
...
Configuring in Spring
Code Block | ||||
---|---|---|---|---|
| ||||
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:cxf="http://cxf.apache.org/core" xmlns:jaxrs="http://cxf.apache.org/jaxrs" xsi:schemaLocation="http://cxf.apache.org/core http://cxf.apache.org/schemas/core.xsd http://cxf.apache.org/jaxrs http://cxf.apache.org/schemas/jaxrs.xsd http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd"> ... <!-- JAXRS providers --> <bean id="jsonProvider" class="com.fasterxml.jackson.jaxrs.json.JacksonJsonProvider" /> <!-- Application resources --> <bean id="sampleResource" class="demo.jaxrs.swagger.server.Sample" /> <!-- CXF Swagger2Feature --> <bean id="swagger2Feature" class="org.apache.cxf.jaxrs.swagger.Swagger2Feature"> <!-- customize some of the properties --> <property name="basePath" value="/app/swaggerSample"/> </bean> ... <jaxrs:server id="sampleServer" address="/swaggerSample"> <jaxrs:serviceBeans> <ref bean="sampleResource" /> </jaxrs:serviceBeans> <jaxrs:providers> <ref bean="jsonProvider" /> </jaxrs:providers> <jaxrs:features> <ref bean="swagger2Feature" /> </jaxrs:features> </jaxrs:server> </beans> |
...
Configuring in Blueprint
...
Code Block | ||||
---|---|---|---|---|
| ||||
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:cxf="http://cxf.apache.org/blueprint/core" xmlns:jaxrs="http://cxf.apache.org/blueprint/jaxrs" xsi:schemaLocation="http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd http://cxf.apache.org/blueprint/core http://cxf.apache.org/schemas/blueprint/core.xsd http://cxf.apache.org/jaxrs http://cxf.apache.org/schemas/blueprint/jaxrs.xsd"> ... <!-- JAXRS providers --> <bean id="jsonProvider" class="com.fasterxml.jackson.jaxrs.json.JacksonJsonProvider" /> <!-- Application resources --> <bean id="sampleResource" class="demo.jaxrs.swagger.server.Sample" /> <!-- CXF Swagger2Feature --> <bean id="swagger2Feature" class="org.apache.cxf.jaxrs.swagger.Swagger2Feature"> <!-- customize some of the properties --> <property name="basePath" value="/cxf/swaggerSample"/> </bean> ... <jaxrs:server id="sampleServer" address="/swaggerSample"> <jaxrs:serviceBeans> <ref component-id="sampleResource" /> </jaxrs:serviceBeans> <jaxrs:providers> <ref component-id="jsonProvider" /> </jaxrs:providers> <jaxrs:features> <ref component-id="swagger2Feature" /> </jaxrs:features> </jaxrs:server> </blueprint> |
Configuring in CXFNonSpringJaxrsServlet
...
Code Block | ||||
---|---|---|---|---|
| ||||
<web-app> <context-param> <param-name>contextParam</param-name> <param-value>contextParamValue</param-value> </context-param> <servlet> <servlet-name>CXFServlet</servlet-name> <display-name>CXF Servlet</display-name> <servlet-class> org.apache.cxf.jaxrs.servlet.CXFNonSpringJaxrsServlet </servlet-class> <init-param> <param-name>jaxrs.serviceClasses</param-name> <param-value> org.apache.cxf.systest.jaxrs.BookStore </param-value> </init-param> <init-param> <param-name>jaxrs.features</param-name> <param-value> org.apache.cxf.jaxrs.swagger.Swagger2Feature (basePath=/somepath) </param-value> </init-param> <load-on-startup>1</load-on-startup> </servlet> <servlet-mapping> <servlet-name>CXFServlet</servlet-name> <url-pattern>/*</url-pattern> </servlet-mapping> </web-app> |
...
See samples/jax_rs/spring_boot and on how to create Swagger2Feature in a @Bean method or/and samples/jax_rs/spring_boot_scan on how to auto-enable it.
Accessing Swagger Documents
...
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.
See samples/jax_rs/description_swagger2, samples/jax_rs/description_swagger2_web, samples/jax_rs/spring_boot and samples/jax_rs/spring_boot_scan
Note that CXF OSGI endpoints can only depend on this feature starting from CXF 3.1.8.
Unpacking Swagger UI resources
Enabling Swagger UI in OSGi container (Karaf)
Since org.webjars/swagger-ui is just a package with resources, it won't be referenced in OSGi manifest as the required imports. Therefore, to make use of Swagger UI in the OSGi deployments, the org.webjars/swagger-ui should be installed manually, for example:
Code Block |
---|
karaf@root()> install mvn:org.webjars/swagger-ui/3.23.8 |
The dedicated Activator will take care of discovering the presence of the org.webjars/swagger-ui bundle and configuring Swagger2Feature.
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.
See Up until CXF 3.1.7 unpacking Swagger UI resources into the local folder was the only option. It is demoed in samples/jax_rs/description_swagger2, samples/jax_rs/description_swagger2_web, samples/jax_rs/spring_boot and samples/jax_rs/descriptionspring_swagger2boot_osgi.scan
Note that CXF OSGI endpoints can only depend on this feature starting from In CXF 3.1.8: set Swagger2Feature 'supportSwaggerUi' property to 'false' to disable the automatic UI activation described in the previous section
Configuring Swagger UI (from 3.2.7+)
...
.
Unpacking Swagger UI resources
Up until CXF 3.1.7 unpacking Swagger UI resources into the local folder was the only option. It is demoed in samples/jax_rs/description_swagger2_spring and samples/jax_rs/description_swagger2_osgi.
In CXF 3.1.8: set Swagger2Feature 'supportSwaggerUi' property to 'false' to disable the automatic UI activation described in the previous section
Configuring Swagger UI (3.2.7+)
The Swagger2Feature 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.
Warning | ||
---|---|---|
Apache CXF prior to 3.4.6 / 3.5.1 passed Swagger UI configuration (url, ...) as query parameters. Starting from Swagger UI 4.1.3, most of query parameters are not accepted anymore (due to security concerns), and Apache CXF employes different strategy and tries to replace the URL dynamically (inside HTML) when serving Swagger UI's front web page. This behaviour could be turned off by setting The typical initialization for server-side dynamical URL replacement looks like this:
In other words:
|
Reverse Proxy
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".
...
- 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
...