Introduction

The CXF OpenApiFeature allows you to generate OpenAPI v3.0 documents from JAX-RS service endpoints with a simple configuration. This feature can be configured programmatically in Java or using Spring or Blueprint beans.

Setup

<dependency>
    <groupId>org.apache.cxf</groupId>
    <artifactId>cxf-rt-rs-service-description-openapi-v3</artifactId>
    <version>3.2.4</version>
</dependency>

The cxf-rt-rs-service-description-openapi-v3 is only available in 3.2.x and above due to Java 8 baseline. For older releases, as well as for the users of older Swagger specifications 1.x/2.x, there is a dedicated converter provided: org.apache.cxf.jaxrs.swagger.openapi.SwaggerToOpenApiConversionFilter.

Properties

The following optional parameters can be configured in OpenApiFeature. Note that although there are some similarities with Swagger specifications 1.x/2.x, OpenAPI v3.0 is a significant revamp of the specification (in a good sense of it).

openapi-configuration.yaml
openapi-configuration.json
openapi.yaml
openapi.json

* - the properties are defined in the OpenAPI class

 ** - the properties are defined in the SwaggerConfiguration class

Configuring from Code

...

import org.apache.cxf.jaxrs.openapi.OpenApiFeature;
import io.swagger.v3.oas.models.security.SecurityScheme;
import io.swagger.v3.oas.models.security.SecurityScheme.Type;

...

final OpenApiFeature feature = new OpenApiFeature();
feature.setContactEmail("cxf@apache.org");
feature.setLicense("Apache 2.0 License");
feature.setLicenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html");           
feature.setSecurityDefinitions(Collections.singletonMap("basicAuth",new SecurityScheme().type(Type.HTTP)));

* - the properties are defined in the OpenAPI class

 ** - the properties are defined in the SwaggerConfiguration class

Configuring from Code

import org.apache.cxf.jaxrs.openapi.OpenApiFeature;
import io.swagger.v3.oas.models.security.SecurityScheme;
import io.swagger.v3.oas.models.security.SecurityScheme.Type;

...

final OpenApiFeature feature = new OpenApiFeature();
feature.setContactEmail("cxf@apache.org");
feature.setLicense("Apache 2.0 License");
feature.setLicenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html");

Configuring from 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
           
feature.setSecurityDefinitions(Collections.singletonMap("basicAuth",new SecurityScheme().type(Type.HTTP)));

Configuring from Spring

<beans xmlns="http://www.springframework.org/schema/beans"                http://cxf.apache.org/jaxrs http://cxf.apache.org/schemas/jaxrs.xsd
                           xmlns:xsi="http://www.springframeworkw3.org/schema/beans 2001/XMLSchema-instance" xmlns:cxf="http://wwwcxf.springframeworkapache.org/schema/beans/spring-beans.xsd">core"
       xmlns:jaxrs="http://cxf... apache.org/jaxrs"
    <!-- JAXRS providers -->
    <bean id="jsonProvider" class="com.fasterxml.jackson.jaxrs.json.JacksonJsonProvider" />
 
    <!-- Application resources -->
    <bean id="sampleResource" class="demo.jaxrs.openapi.server.Sample" />
 
    <!-- CXF OpenApiFeature -->  
    <bean id="openApiFeature" class="org.apache.cxf.jaxrs.openapi.OpenApiFeature 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">
    ... 
    <!-- customize some of the properties JAXRS providers -->
    <bean id="jsonProvider"  </bean>class="com.fasterxml.jackson.jaxrs.json.JacksonJsonProvider" />
 
     ...
<!-- Application resources -->
    <jaxrs:server<bean id="sampleServersampleResource" addressclass="/swaggerSample"demo.jaxrs.openapi.server.Sample" />
 
    <!-- CXF  <jaxrs:serviceBeans>
OpenApiFeature -->  
    <bean      <ref bean="sampleResource" /id="openApiFeature" class="org.apache.cxf.jaxrs.openapi.OpenApiFeature">
        </jaxrs:serviceBeans>
        <jaxrs:providers>
   !-- customize some of the properties -->
    </bean>
 
    ...

     <ref bean<jaxrs:server id="jsonProvidersampleServer" address="/>
        </jaxrs:providers>swaggerSample">
        <jaxrs:features>serviceBeans>
            <ref bean="openApiFeaturesampleResource" />
        </jaxrs:features>
serviceBeans>
        <jaxrs:providers>
            <ref bean="jsonProvider" />
        </jaxrs:server>
</beans>

Configuring in Blueprint

providers>
        <jaxrs:features>
            <ref bean="openApiFeature" />
        </jaxrs:features>
    </jaxrs:server>
</beans>

Configuring in Blueprint

In case of Apache Karaf, the OpenAPI v3.0 integration is available as cxf-rs-description-openapi-v3 feature.

...

<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.openapi.server.Sample" />
 
 
    <!-- CXF OpenApiFeature -->  
    <bean id="openApiFeature" class="org.apache.cxf.jaxrs.openapi.OpenApiFeature">
        <!-- customize some of the properties -->
    </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="openApiFeature" />
        </jaxrs:features>
    </jaxrs:server>
</blueprint>

Configuring in CXFNonSpringJaxrsServlet

<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.openapi.OpenApiFeature</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>

Configuring from Property files

It is possible to supply the configuration from the property files. The default location for a properties file is "/swagger.properties". OpenApiFeature will pick it up if it is available, and the location can be overridden with a 'propertiesLocation' property.  Additionally, the complete OpenAPI configuration could be supplied from the property file (usually openapi-configuration.json or openapi-configuration.yml), controlled by 'configLocation' property. Please take into account that there is a certain level of the overlap between both.

Note that the properties, if available, do not override the properties which may have been set as suggested above from the code or Spring/Blueprint contexts or web.xml. Instead they complement and serve as the default configuration properties: for example, if some properties have been set from the code then the values for the same properties found in the properties file will not be used.

Spring Boot Auto Configuration

Please consult samples/jax_rs/spring_boot and on how to create OpenApiFeature as a @Bean and samples/jax_rs/spring_boot_scan on how to auto-enable it.

Enabling Swagger UI

Adding a Swagger UI Maven dependency is all what is needed to start accessing Swagger documents with the help of Swagger UI.

.apache.cxf.jaxrs.openapi.OpenApiFeature</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>

Configuring from Property files

It is possible to supply the configuration from the property files. The default location for a properties file is "/swagger.properties". OpenApiFeature will pick it up if it is available, and the location can be overridden with a 'propertiesLocation' property.  Additionally, the complete OpenAPI configuration could be supplied from the property file (usually openapi-configuration.json or openapi-configuration.yml), controlled by 'configLocation' property. By default, OpenApiFeature scans for known OpenAPI configuration locations and loads them if available (the behavior could be switched off by setting scanKnownConfigLocations to false). Please take into account that there is a certain level of the overlap between both.

Note that the properties, if available, do not override the properties which may have been set as suggested above from the code or Spring/Blueprint contexts or web.xml. Instead they complement and serve as the default configuration properties: for example, if some properties have been set from the code then the values for the same properties found in the properties file will not be used.

Spring Boot Auto Configuration

Please consult samples/jax_rs/spring_boot and on how to create OpenApiFeature as a @Bean or/and samples/jax_rs/spring_boot_scan on how to auto-enable it. By default, the OpenApiCustomizer instance will be preconfigured for  OpenApiFeature since the base path is often unknown to CXF.

Enabling Swagger UI

Adding a Swagger UI Maven dependency is all what is needed to start accessing Swagger documents with the help of Swagger UI.

<dependency>
    <groupId>org.webjars</groupId>
    <artifactId>swagger-ui</artifactId>
    <version>3.13.0</version>
</dependency>

karaf@root()> install mvn:org.webjars/swagger-ui/3.23.8

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

final OpenApiFeature feature = new OpenApiFeature();
feature.setScan(false);
feature.setUseContextBasedConfig(true);
...

<dependency>
    <groupId>org.webjars</groupId>
    <artifactId>swagger-ui</artifactId>
    <version>3.13.0</version>
</dependency>