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 and is an alternative to Swagger's OpenApiFeature.

Setup

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

The cxf-rt-rs-service-description-microprofile-openapi is only available in 3.4.0. For older releases, please consider Swagger's OpenApiFeature instead.

Properties

The following optional parameters can be configured in OpenApiFeature (please note there are some differences comparing to Swagger's OpenApiFeature).

configLocation

the OpenAPI configuration location

null/config/openapi-configuration.yml
scanKnownConfigLocations

scan known OpenAPI configuration location (classpath or filesystem), which are:

openapi-configuration.yaml
openapi-configuration.json
openapi.yaml
openapi.json
truetrue
propertiesLocationthe properties file location/swagger.properties /swagger.properties
swaggerUiMavenGroupAndArtifactthe Maven artifacts to pinpoint SwaggerUInull"org.webjars.swagger-ui'
swaggerUiVersionthe version of SwaggerUInull"3.13.0"
supportSwaggerUiturns on/off SwaggerUI supportnull (== true)true
filterClassa security filter**null"com.example.filter.SampleFilter"
resourceClassesa list of resource classes which must be scanned**null["com.example.rest.SampleResource"]
resourcePackagesa list of package names where resources must be scanned**null["com.example.rest"]
ignoredRoutesexcludes specific paths when scanning all resources (see scanAllResources)**null["/api/test"]
prettyPrintwhen generating openapi.json, pretty-print the JSON document**truetrue
runAsFilterruns the feature as a filterfalsefalse
scanScan all JAX-RS resources automaticallytruetrue
readAllResourcesRead all operations also with no @Operation** truetrue
termsOfServiceUrlthe terms of service URL*nullnull
licenseUrlthe license URL*null"http://www.apache.org/licenses/LICENSE-2.0.html"
licensethe license*null"Apache 2.0 License"
contactUrlthe contact link*nullnull
contactEmailthe contact email*null"users@cxf.apache.org"
contactNamethe contact name*nullnull
descriptionthe description*null"The Sample REST Application with OpenAPI integration"
titlethe title*null"Sample REST Application"
versionthe version*null"1.0.0"
swaggerUiConfigSwagger UI configurationnullnew SwaggerUiConfig().url("/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.microprofile.openapi.OpenApiFeature;
 
...
 
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
                           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.openapi.server.Sample" />
  
    <!-- CXF OpenApiFeature (Microprofile) --> 
    <bean id="openApiFeature" class="org.apache.cxf.jaxrs.microprofile.openapi.OpenApiFeature">
        <!-- customize some of the properties -->
    </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="openApiFeature" />
        </jaxrs:features>
    </jaxrs:server>
</beans>

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. 

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.

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>


For example, let's assume a JAX-RS endpoint is published at 'http://host:port/context/services/'.

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

CXF Services page will also link to Swagger UI. Go to 'http://host:port/context/services/' and follow a Swagger link which will return a Swagger UI page.

See samples/jax_rs/description_openapi_microprofile_spring as an example.

To deactivate automatic Swagger UI integration please set 'supportSwaggerUi' property to "false".

Configuring Swagger UI

The OpenApiFeature  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. The way it is implemented is by passing those parameters as a query string so the Swagger UI could adjust itself.

Samples

CXF's distribution contains the following samples.

  • No labels