CXF配置swagger2

SwaggerFeature / Swagger2Feature

 

• SwaggerFeature / Swagger2Feature
• Setup
• Properties
• Configuring Programatically
• Configuring in Spring
• Configuring in Blueprint
• Configuring in CXFNonSpringJaxrsServlet
• Enabling in Spring Boot
• Accessing Swagger Documents
• Enabling Swagger UI
  • Automatic UI Activation
  • Unpacking Swagger UI resources
• Samples

 

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.

These features can be configured programatically in Java or using Spring or Blueprint beans.

Setup

<dependency>     <groupId>org.apache.cxfgroupId>     <artifactId>cxf-rt-rs-service-description-swaggerartifactId>     <version>3.1.7version> 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 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.)

Name	Description	Default
basePath	the context root path+	null
contact	the contact information+	"[email protected]"
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+	"http://www.apache.org/licenses/LICENSE-2.0.html"
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"
version	the version+	"1.0.0"

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

 

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

 

<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">     ...           <bean id="jsonProvider" class="com.fasterxml.jackson.jaxrs.json.JacksonJsonProvider" />            <bean id="sampleResource" class="demo.jaxrs.swagger.server.Sample" />             <bean id="swagger2Feature" class="org.apache.cxf.jaxrs.swagger.Swagger2Feature">                  <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

 

<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">      ...          <bean id="jsonProvider" class="com.fasterxml.jackson.jaxrs.json.JacksonJsonProvider" />             <bean id="sampleResource" class="demo.jaxrs.swagger.server.Sample" />               <bean id="swagger2Feature" class="org.apache.cxf.jaxrs.swagger.Swagger2Feature">                  <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

 

<web-app>     <context-param>         <param-name>contextParamparam-name>         <param-value>contextParamValueparam-value>     context-param>     <servlet>         <servlet-name>CXFServletservlet-name>         <display-name>CXF Servletdisplay-name>         <servlet-class>               org.apache.cxf.jaxrs.servlet.CXFNonSpringJaxrsServlet         servlet-class>         <init-param>             <param-name>jaxrs.serviceClassesparam-name>             <param-value>                            org.apache.cxf.systest.jaxrs.BookStore             param-value>         init-param>         <init-param>             <param-name>jaxrs.featuresparam-name>             <param-value>                         org.apache.cxf.jaxrs.swagger.Swagger2Feature                         (basePath=/somepath)             param-value>         init-param>         <load-on-startup>1load-on-startup>     servlet>           <servlet-mapping>         <servlet-name>CXFServletservlet-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.

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.

Enabling Swagger UI

First one needs to add the following

<dependency>     <groupId>org.webjarsgroupId>     <artifactId>swagger-uiartifactId>     <version>2.1.8-M1version> 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.

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/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

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.

• 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