Page History

Versions Compared

Old Version 23

changes.mady.by.user Unknown User (reta)

Saved on Dec 02, 2018

compared with

New Version 24

changes.mady.by.user Unknown User (reta)

Saved on Sep 07, 2019

Key

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

...

Name

Description

Default value (if applicable)

Sample value (if applicable)

configLocation

the OpenAPI configuration location

null

/config/openapi-configuration.yml

scanKnownConfigLocations

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

No Format
openapi-configuration.yaml openapi-configuration.json openapi.yaml openapi.json

true

propertiesLocation

the properties file location

/swagger.properties

securityDefinitions

a list of security definitions*

null

["basicAuth" -> new SecurityScheme().type(Type.HTTP))]

customizer

the customizer class instance

null

new OpenApiCustomizer()

swaggerUiMavenGroupAndArtifact

the Maven artifacts to pinpoint SwaggerUI

null

"org.webjars.swagger-ui'

swaggerUiVersion

the version of SwaggerUI

null

"3.13.0"

supportSwaggerUi

turns on/off SwaggerUI support

null (== true)

true

filterClass

a security filter**

null

"com.example.filter.SampleFilter"

resourceClasses

a list of resource classes which must be scanned**

null

["com.example.rest.SampleResource"]

resourcePackages

a list of package names where resources must be scanned**

null

["com.example.rest"]

ignoredRoutes

excludes specific paths when scanning all resources (see scanAllResources)**

null

["/api/test"]

prettyPrint

when generating openapi.json, pretty-print the JSON document**

true

true

runAsFilter

runs the feature as a filter

false

false

scan

Scan all JAX-RS resources automatically

true

true

readAllResources

Read all operations also with no @Operation**

true

true

termsOfServiceUrl

the terms of service URL*

null

licenseUrl

the license URL*

null

"http://www.apache.org/licenses/LICENSE-2.0.html"

license

the license*

null

"Apache 2.0 License"

contactUrl

the contact link*

null

contactEmail

the contact email*

null

"users@cxf.apache.org"

contactName

the contact name*

null

description

the description*

null

"The Sample REST Application with OpenAPI integration"

title

the title*

null

"Sample REST Application"

version

the version*

null

"1.0.0"

swaggerUiConfig

Swagger UI configuration

null

new SwaggerUiConfig().url("/openapi.json")

useContextBasedConfig

If set, the unique Context Id is going to be generated for each OpenApiContext instance (see please Using Multiple Server Endpoints). Also, you very likely may want to set scan property to false.

false

false

scannerClass

the name of the JAX-RS API scanner class, used to scope the application, resource packages, resource classes and classpath scanning

null

io.swagger.v3.jaxrs2.integration.JaxrsApplicationScanner

* - the properties are defined in the OpenAPI class

...

Code Block

	java
	java

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)));

Configuring from 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.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 bean="sampleResource" />
        </jaxrs:serviceBeans>
        <jaxrs:providers>
            <ref bean="jsonProvider" />
        </jaxrs: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.

...

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

...

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

...

Code Block

	xml
	xml

<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_v3 as an example.

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

Configuring Swagger UI (3.2.7+)

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

Anchor
OpenApiFeature-UsingMultipleServerEndpoints(3.3.0+)
OpenApiFeature-UsingMultipleServerEndpoints(3.3.0+)
Using Multiple Server Endpoints (3.3.0+)

Quite often there are more than one JAXRSServerFactoryBean configured within same Apache CXF application, for example, under "/admin" and "/public" endpoints. The older Swagger/OpenAPI v2.0 integrations used such basePath to disambiguate multiple API documentation contexts, but since OpenAPI v3.0 Specification does not explicitly include the concept of basePath anymore, this approach is not working. Luckily, starting from 2.0.6 release, Swagger OpenAPI v3 implementation properly supports Context Id. To activate it from OpenApiFeature, it is enough to set useContextBasedConfig property to true (very likely you would also want to set scan to false).

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

With that, each OpenApiFeature will generate unique Context Id and won't see any classes / packages beyond its own configuration.

Samples

CXF's distribution contains the following samples.

samples/jax_rs/description_openapi_v3: the OpenAPI v3.0 standalone sample using OpenApiFeature programmatically
samples/jax_rs/description_openapi_v3_osgi: the OpenAPI v3.0 OSGi application sample using OpenApiFeature using Blueprint
samples/jax_rs/description_openapi_v3_web: the OpenAPI v3.0 sample using OpenApiFeature inside WAR-based deployment
samples/jax_rs/description_openapi_v3_spring: the OpenAPI v3.0 sample using Spring and multiple context paths / OpenApiFeatures

Overview

Content Tools

Child pages

Page History

Versions Compared

Old Version 23

New Version 24

Key

Configuring from Spring

Configuring in Blueprint

Configuring in CXFNonSpringJaxrsServlet

Configuring Swagger UI (3.2.7+)

AnchorOpenApiFeature-UsingMultipleServerEndpoints(3.3.0+)OpenApiFeature-UsingMultipleServerEndpoints(3.3.0+)Using Multiple Server Endpoints (3.3.0+)

Samples

Anchor
OpenApiFeature-UsingMultipleServerEndpoints(3.3.0+)
OpenApiFeature-UsingMultipleServerEndpoints(3.3.0+)
Using Multiple Server Endpoints (3.3.0+)