...
Swagger2Feature
Table of Contents |
---|
The CXF Swagger2Feature allows you to generate Swagger 2.0 documents from JAX-RS service endpoints with a simple configuration.
...
These features can be configured programatically in Java or using Spring or Blueprint beans.
Setup
Code Block | ||
---|---|---|
| ||
<dependency> <groupId>org.apache.cxf</groupId> <artifactId>cxf-rt-rs-service-description-swagger</artifactId> <version>3.1.7</version> </dependency> |
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 Programatically
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> |
Enabling in Spring Boot
See samples/jax_rs/spring_boot and on how to create Swagger2Feature in a @Bean method and samples/jax_rs/spring_boot_scan on how to auto-enable it.
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.
...
In the above example, go to 'http://host:port/context/services/services' and follow a Swagger link which will return a Swagger JSON document.
Enabling Swagger UI
First one needs to add the following
Code Block | ||
---|---|---|
| ||
<dependency> <groupId>org.webjars</groupId> <artifactId>swagger-ui</artifactId> <version>2.1.8-M1</version> </dependency> |
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.
...
Note that CXF OSGI endpoints can only depend on this feature starting from CXF 3.1.8.
Unpacking Swagger UI resources
Up until CXF 3.1.7 unpacking Swagger UI resources into the local folder has been the only option. It is demoed in all CXF Swagger demos but samples/jax_rs/description_swagger2 which
shows the automatic UI activation. In CXF 3.1.7: set Swagger2Feature 'supportSwaggerUi' property to 'false' to disable to automatic UI activation described in the previous section
Samples
CXF's distribution contains the following samples.
...