Page History

Versions Compared

Old Version 29

changes.mady.by.user Andriy Redko

Saved on Apr 08, 2018

compared with

New Version Current

changes.mady.by.user Andriy Redko

Saved on May 20, 2023

Key

This line was added.
This line was removed.
Formatting was changed.

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 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+	null (in CXF 3.1.x "users@cxf.apache.org")
description	the description+	null (in CXF 3.1.x "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+	null (in CXF 3.1.x "Sample REST Application")
version	the version+	null (in CXF 3.1.x "1.0.0")
swaggerUiConfig	Swagger UI configuration	null

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

	java
	java

import org.apache.cxf.frontend.ServerFactoryBean;
import org.apache.cxf.jaxrs.swagger.Swagger2Feature;
...

    Swagger2Feature feature = new Swagger2Feature();

    // customize some of the properties
    featurefeature.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

	xml
	xml

<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

	xml
	xml

<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

	xml
	xml

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

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://Open the browser and go to 'http://host:port/context/services/'.

Open the browser and go to 'http://host:port/context/services/apiapi-docs/?url=/swagger.json' which will return a Swagger UI page.

...

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 queryConfigEnabled property of the SwaggerUiConfig to true (the default value is false and URLs are replaced dynamically). Please notice that in this case the customized Swagger UI bundle is required since queryConfigEnabled property could only be set by altering the distribution (https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md).

The typical initialization for server-side dynamical URL replacement looks like this:

Code Block
new SwaggerUiConfig() .url("/swagger.json") ... .queryConfigEnabled(false)

In other words:

when queryConfigEnabled is set to false, Apache CXF will dynamically replace the URL in SwaggerUI, in this respect the value won't be taken from the query string but from url property of the SwaggerUI configuration, this is a default behavior
when queryConfigEnabled is set to true, Apache CXF will do nothing and just forward query parameters to SwaggerUI (hoping it will somehow take care of it), in generalthat implies custom SwaggerUI distribution has to be used

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

...

Overview

Content Tools

Apps

Child pages

Page History

Versions Compared

Old Version 29

New Version Current

Key

Swagger2Feature

Properties

Configuring from Code

Configuring in Spring

Configuring in Blueprint

Configuring in CXFNonSpringJaxrsServlet

Accessing Swagger Documents

Enabling Swagger UI

Automatic UI Activation

Enabling Swagger UI in OSGi container (Karaf)

Automatic UI Activation

Configuring Swagger UI (3.2.

7+)

Reverse Proxy