Swagger2Feature
Properties
The CXF Swagger2Feature allows you to generate Swagger 2.0 documents from JAX-RS service endpoints with a simple configuration.
This feature can be configured programatically in Java or using Spring or Blueprint beans.
The following optional parameters can be configured in Swagger2Feature.
Name | Description | Default |
---|---|---|
basePath | the context root path+ | null |
contact | the contact information+ | "users@cxf.apache.org" |
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" |
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"> ... <!-- 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
<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>