Versions Compared

Old Version 32

changes.mady.by.user Andriy Redko

Saved on

compared with

New Version 33

changes.mady.by.user Andriy Redko

Saved on

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: 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
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
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
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 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.
...
...