Versions Compared

Old Version 30

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

Saved on

compared with

New Version Current

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

Saved on

Key

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

...

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

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

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.


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


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.