Swagger2Feature
Table of Contents |
---|
Swagger2Feature
The CXF Swagger2Feature allows you to generate Swagger 2.0 (http://swagger.io/specification/) 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 marked with + in the description field correspond to the properties defined in Swagger's BeanConfig, those marked with ++ correspond to 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>
|