You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cxf.apache.org by bu...@apache.org on 2022/05/31 23:42:53 UTC
svn commit: r1079714 - in /websites/production/cxf/content: cache/docs.pageCache docs/openapifeature.html docs/swagger2feature.html
Author: buildbot
Date: Tue May 31 23:42:53 2022
New Revision: 1079714
Log:
Production update by buildbot for cxf
Modified:
websites/production/cxf/content/cache/docs.pageCache
websites/production/cxf/content/docs/openapifeature.html
websites/production/cxf/content/docs/swagger2feature.html
Modified: websites/production/cxf/content/cache/docs.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/cxf/content/docs/openapifeature.html
==============================================================================
--- websites/production/cxf/content/docs/openapifeature.html (original)
+++ websites/production/cxf/content/docs/openapifeature.html Tue May 31 23:42:53 2022
@@ -110,11 +110,11 @@ Apache CXF -- OpenApiFeature
<!-- Content -->
<div class="wiki-content">
<div id="ConfluenceContent"><p><style type="text/css">/*<![CDATA[*/
-div.rbtoc1651074332363 {padding: 0px;}
-div.rbtoc1651074332363 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1651074332363 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1654040571314 {padding: 0px;}
+div.rbtoc1654040571314 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1654040571314 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1651074332363">
+/*]]>*/</style></p><div class="toc-macro rbtoc1654040571314">
<ul class="toc-indentation"><li><a shape="rect" href="#OpenApiFeature-Introduction">Introduction</a></li><li><a shape="rect" href="#OpenApiFeature-Setup">Setup</a></li><li><a shape="rect" href="#OpenApiFeature-Properties">Properties</a></li><li><a shape="rect" href="#OpenApiFeature-ConfiguringfromCode">Configuring from Code</a></li><li><a shape="rect" href="#OpenApiFeature-ConfiguringfromSpring">Configuring from Spring</a></li><li><a shape="rect" href="#OpenApiFeature-ConfiguringinBlueprint">Configuring in Blueprint</a></li><li><a shape="rect" href="#OpenApiFeature-ConfiguringinCXFNonSpringJaxrsServlet">Configuring in CXFNonSpringJaxrsServlet</a></li><li><a shape="rect" href="#OpenApiFeature-ConfiguringfromPropertyfiles">Configuring from Property files</a></li><li><a shape="rect" href="#OpenApiFeature-SpringBootAutoConfiguration">Spring Boot Auto Configuration</a></li><li><a shape="rect" href="#OpenApiFeature-EnablingSwaggerUI">Enabling Swagger UI</a>
<ul class="toc-indentation"><li><a shape="rect" href="#OpenApiFeature-EnablingSwaggerUIinOSGicontainer(Karaf)">Enabling Swagger UI in OSGi container (Karaf)</a></li><li><a shape="rect" href="#OpenApiFeature-ConfiguringSwaggerUI(3.2.7+)">Configuring Swagger UI (3.2.7+)</a></li></ul>
</li><li><a shape="rect" href="#OpenApiFeature-OpenApiFeature-UsingMultipleServerEndpoints(3.3.0+)UsingMultipleServerEndpoints(3.3.0+)">Using Multiple Server Endpoints (3.3.0+)</a></li><li><a shape="rect" href="#OpenApiFeature-Samples">Samples</a></li></ul>
@@ -239,15 +239,15 @@ feature.setSecurityDefinitions(Collectio
</servlet-mapping>
</web-app></pre>
-</div></div><h1 id="OpenApiFeature-ConfiguringfromPropertyfiles">Configuring from Property files</h1><p>It is possible to supply the configuration from the property files. The default location for a properties file is "<strong>/swagger.properties</strong>". <strong>OpenApiFeature</strong> will pick it up if it is available, and the location can be overridden with a<strong> 'propertiesLocation</strong>' property.  Additionally, the complete OpenAPI configuration could be supplied from the property file (usually <strong>openapi-configuration.json</strong> or <strong>openapi-configuration.yml</strong>), controlled by '<strong>configLocation'</strong> property. By default, <strong>OpenApiFeature</strong> scans for known OpenAPI configuration locations and loads them if available (the behavior could be switched off by setting <strong>scanKnownConfigLocations</strong> to <strong>false</strong>). Please take into account that there is a certain level of the overlap between b
oth.</p><p>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.</p><h1 id="OpenApiFeature-SpringBootAutoConfiguration">Spring Boot Auto Configuration</h1><p>Please consult <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/spring_boot" rel="nofollow">samples/jax_rs/spring_boot</a> and on how to create <strong>OpenApiFeature</strong> as a @Bean or/and <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/distribution/src/main/release/samples/jax_rs/spring_boot_scan/application/src/main/resources/application.yml#L13" rel="nofollow">sample
s/jax_rs/spring_boot_scan</a> on how to auto-enable it. By default, the <strong>OpenApiCustomizer</strong> instance will be preconfigured for  <strong>OpenApiFeature</strong> since the base path is often unknown to CXF.</p><h1 id="OpenApiFeature-EnablingSwaggerUI">Enabling Swagger UI</h1><p>Adding a Swagger UI Maven dependency is all what is needed to start accessing Swagger documents with the help of Swagger UI.</p><div class="syntaxhighlighter nogutter xml"><p><br clear="none"></p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"><dependency>
+</div></div><h1 id="OpenApiFeature-ConfiguringfromPropertyfiles">Configuring from Property files</h1><p>It is possible to supply the configuration from the property files. The default location for a properties file is "<strong>/swagger.properties</strong>". <strong>OpenApiFeature</strong> will pick it up if it is available, and the location can be overridden with a<strong> 'propertiesLocation</strong>' property.  Additionally, the complete OpenAPI configuration could be supplied from the property file (usually <strong>openapi-configuration.json</strong> or <strong>openapi-configuration.yml</strong>), controlled by '<strong>configLocation'</strong> property. By default, <strong>OpenApiFeature</strong> scans for known OpenAPI configuration locations and loads them if available (the behavior could be switched off by setting <strong>scanKnownConfigLocations</strong> to <strong>false</strong>). Please take into account that there is a certain level of the overlap between b
oth.</p><p>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.</p><h1 id="OpenApiFeature-SpringBootAutoConfiguration">Spring Boot Auto Configuration</h1><p>Please consult <a shape="rect" class="external-link" rel="nofollow" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/spring_boot">samples/jax_rs/spring_boot</a> and on how to create <strong>OpenApiFeature</strong> as a @Bean or/and <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/distribution/src/main/release/samples/jax_rs/spring_boot_scan/application/src/main/resources/application.yml#L13" rel="nofollow">sample
s/jax_rs/spring_boot_scan</a> on how to auto-enable it. By default, the <strong>OpenApiCustomizer</strong> instance will be preconfigured for  <strong>OpenApiFeature</strong> since the base path is often unknown to CXF.</p><h1 id="OpenApiFeature-EnablingSwaggerUI">Enabling Swagger UI</h1><p>Adding a Swagger UI Maven dependency is all what is needed to start accessing Swagger documents with the help of Swagger UI.</p><div class="syntaxhighlighter nogutter xml"><p><br clear="none"></p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: xml; gutter: false; theme: Default"><dependency>
<groupId>org.webjars</groupId>
<artifactId>swagger-ui</artifactId>
<version>3.13.0</version>
</dependency></pre>
</div></div><p><br clear="none"></p><p>For example, let's assume a JAX-RS endpoint is published at '<span><a shape="rect" class="external-link" href="http://hostport" rel="nofollow">http://host:port/context/services/</a></span>'.</p><p>Open the browser and go to '<span><a shape="rect" class="external-link" href="http://hostport" rel="nofollow">http://host:port/context/services/</a></span>api-docs/?url=/openapi.json' which will return a Swagger UI page.</p><p>CXF Services page will also link to Swagger UI. Go to '<span><a shape="rect" class="external-link" href="http://hostport" rel="nofollow">http://host:port/context/services/</a></span>' and follow a Swagger link which will return a Swagger UI page.</p><p>See <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_openapi_v3" rel="nofollow">samples/jax_rs/description_openapi_v3</a> as an example.</p><p>To deactivate automatic Swagger UI inte
gration please set<strong> 'supportSwaggerUi'</strong> property to "<strong>false</strong>".</p><h2 id="OpenApiFeature-EnablingSwaggerUIinOSGicontainer(Karaf)">Enabling Swagger UI in OSGi container (Karaf)</h2><p>Since <strong>org.webjars</strong>/<strong>swagger-ui</strong> 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 <strong>org.webjars</strong>/<strong>swagger-ui</strong> should be installed manually, for example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default">karaf@root()> install mvn:org.webjars/swagger-ui/3.23.8</pre>
-</div></div><p>The dedicated Activator will take care of discovering the presence of the <strong>org.webjars</strong>/<strong>swagger-ui</strong> bundle and configuring <strong>OpenApiFeature</strong>.</p><h2 id="OpenApiFeature-ConfiguringSwaggerUI(3.2.7+)">Configuring Swagger UI (3.2.7+)</h2><p>The <strong>OpenApiFeature</strong>  has a way to pre-configure certain  Swagger UI parameters (<a shape="rect" class="external-link" href="https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md" rel="nofollow">https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md</a>) through <strong><span class="blob-code-inner blob-code-marker-addition"><span class="pl-smi">SwaggerUiConfig</span></span></strong><span class="blob-code-inner blob-code-marker-addition">. The</span><strong><span class="blob-code-inner blob-code-marker-addition"> </span></strong>way it is implemented is by passing those parameters as a query string so the Swagger
UI could adjust itself.</p><h1 id="OpenApiFeature-OpenApiFeature-UsingMultipleServerEndpoints(3.3.0+)UsingMultipleServerEndpoints(3.3.0+)"><span class="confluence-anchor-link" id="OpenApiFeature-OpenApiFeature-UsingMultipleServerEndpoints(3.3.0+)"></span>Using Multiple Server Endpoints (3.3.0+)</h1><p>Quite often there are more than one <strong>JAXRSServerFactoryBean</strong> configured within same Apache CXF application, for example, under <strong>"/admin"</strong> and <strong>"/public"</strong> endpoints. The older <strong>Swagger/OpenAPI v2.0</strong> integrations used such <strong>basePath</strong> to disambiguate multiple API documentation contexts, but since <strong>OpenAPI v3.0 Specification</strong> does not explicitly include the concept of <strong>basePath</strong> anymore, this approach is not working. Luckily, starting from <strong>2.0.6</strong> release, Swagger OpenAPI v3 implementation properly supports <strong>Context Id</strong>. To activate it from <strong>OpenApi
Feature</strong>, it is enough to set <strong>useContextBasedConfig </strong>property to <strong>true</strong> (very likely you would also want to set <strong>scan</strong> to <strong>false</strong>).</p><p><br clear="none"></p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>The dedicated Activator will take care of discovering the presence of the <strong>org.webjars</strong>/<strong>swagger-ui</strong> bundle and configuring <strong>OpenApiFeature</strong>.</p><h2 id="OpenApiFeature-ConfiguringSwaggerUI(3.2.7+)">Configuring Swagger UI (3.2.7+)</h2><p>The <strong>OpenApiFeature</strong>  has a way to pre-configure certain  Swagger UI parameters (<a shape="rect" class="external-link" href="https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md" rel="nofollow">https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md</a>) through <strong><span class="blob-code-inner blob-code-marker-addition"><span class="pl-smi">SwaggerUiConfig</span></span></strong><span class="blob-code-inner blob-code-marker-addition">. The</span><strong><span class="blob-code-inner blob-code-marker-addition"> </span></strong>way it is implemented is by passing those parameters as a query string so the Swagger
UI could adjust itself.</p></div><p><br clear="none"></p><div class="confluence-information-macro confluence-information-macro-warning"><span class="aui-icon aui-icon-small aui-iconfont-error confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>Apache CXF prior to 3.4.6 / 3.5.1 passed Swagger UI configuration (url, ...) as query parameters. Starting from Swagger UI <strong>4.1.3</strong>, 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 <strong>turned on </strong>by setting <code>queryConfigEnabled</code>  property of the <strong><span class="blob-code-inner blob-code-marker-addition"><span class="pl-smi">SwaggerUiConfig </span></span></strong><span class="blob-code-inner blob-code-marker-addition"><span class="pl-smi">to <code>true</code> (the defa
ult value is <code>false</code> ).</span></span></p></div></div><p><br clear="none"></p><div class="syntaxhighlighter nogutter xml"><h1 id="OpenApiFeature-OpenApiFeature-UsingMultipleServerEndpoints(3.3.0+)UsingMultipleServerEndpoints(3.3.0+)"><span class="confluence-anchor-link" id="OpenApiFeature-OpenApiFeature-UsingMultipleServerEndpoints(3.3.0+)"></span>Using Multiple Server Endpoints (3.3.0+)</h1><p>Quite often there are more than one <strong>JAXRSServerFactoryBean</strong> configured within same Apache CXF application, for example, under <strong>"/admin"</strong> and <strong>"/public"</strong> endpoints. The older <strong>Swagger/OpenAPI v2.0</strong> integrations used such <strong>basePath</strong> to disambiguate multiple API documentation contexts, but since <strong>OpenAPI v3.0 Specification</strong> does not explicitly include the concept of <strong>basePath</strong> anymore, this approach is not working. Luckily, starting from <strong>2.0.6</strong> release, Swagger
OpenAPI v3 implementation properly supports <strong>Context Id</strong>. To activate it from <strong>OpenApiFeature</strong>, it is enough to set <strong>useContextBasedConfig </strong>property to <strong>true</strong> (very likely you would also want to set <strong>scan</strong> to <strong>false</strong>).</p><p><br clear="none"></p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default">final OpenApiFeature feature = new OpenApiFeature();
feature.setScan(false);
feature.setUseContextBasedConfig(true);
Modified: websites/production/cxf/content/docs/swagger2feature.html
==============================================================================
--- websites/production/cxf/content/docs/swagger2feature.html (original)
+++ websites/production/cxf/content/docs/swagger2feature.html Tue May 31 23:42:53 2022
@@ -110,11 +110,11 @@ Apache CXF -- Swagger2Feature
<!-- Content -->
<div class="wiki-content">
<div id="ConfluenceContent"><h1 id="Swagger2Feature-Swagger2Feature">Swagger2Feature</h1><p><style type="text/css">/*<![CDATA[*/
-div.rbtoc1651074186054 {padding: 0px;}
-div.rbtoc1651074186054 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1651074186054 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1654040568170 {padding: 0px;}
+div.rbtoc1654040568170 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1654040568170 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1651074186054">
+/*]]>*/</style></p><div class="toc-macro rbtoc1654040568170">
<ul class="toc-indentation"><li><a shape="rect" href="#Swagger2Feature-Swagger2Feature">Swagger2Feature</a></li><li><a shape="rect" href="#Swagger2Feature-Setup">Setup</a></li><li><a shape="rect" href="#Swagger2Feature-Properties">Properties</a></li><li><a shape="rect" href="#Swagger2Feature-ConfiguringfromCode">Configuring from Code</a></li><li><a shape="rect" href="#Swagger2Feature-ConfiguringinSpring">Configuring in Spring</a></li><li><a shape="rect" href="#Swagger2Feature-ConfiguringinBlueprint">Configuring in Blueprint</a></li><li><a shape="rect" href="#Swagger2Feature-ConfiguringinCXFNonSpringJaxrsServlet">Configuring in CXFNonSpringJaxrsServlet</a></li><li><a shape="rect" href="#Swagger2Feature-New:ConfiguringfromPropertiesfile">New: Configuring from Properties file</a></li><li><a shape="rect" href="#Swagger2Feature-EnablinginSpringBoot">Enabling in Spring Boot</a></li><li><a shape="rect" href="#Swagger2Feature-AccessingSwaggerDocuments">Accessing Swagger Documents</a></li><l
i><a shape="rect" href="#Swagger2Feature-EnablingSwaggerUI">Enabling Swagger UI</a>
<ul class="toc-indentation"><li><a shape="rect" href="#Swagger2Feature-EnablingSwaggerUIinOSGicontainer(Karaf)">Enabling Swagger UI in OSGi container (Karaf)</a></li><li><a shape="rect" href="#Swagger2Feature-AutomaticUIActivation">Automatic UI Activation</a></li><li><a shape="rect" href="#Swagger2Feature-UnpackingSwaggerUIresources">Unpacking Swagger UI resources</a></li><li><a shape="rect" href="#Swagger2Feature-ConfiguringSwaggerUI(3.2.7+)">Configuring Swagger UI (3.2.7+)</a></li></ul>
</li><li><a shape="rect" href="#Swagger2Feature-ReverseProxy">Reverse Proxy</a></li><li><a shape="rect" href="#Swagger2Feature-ConvertingtoOpenAPIJSON">Converting to OpenAPI JSON</a></li><li><a shape="rect" href="#Swagger2Feature-Samples">Samples</a></li></ul>
@@ -254,7 +254,7 @@ sfb.getFeatures().add(feature);</pre>
</pre>
</div></div><p>The newest version 3.x of swagger-ui can also be used.</p><h2 id="Swagger2Feature-EnablingSwaggerUIinOSGicontainer(Karaf)">Enabling Swagger UI in OSGi container (Karaf)</h2><p>Since <strong>org.webjars</strong>/<strong>swagger-ui</strong> 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 <strong>org.webjars</strong>/<strong>swagger-ui</strong> should be installed manually, for example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default">karaf@root()> install mvn:org.webjars/swagger-ui/3.23.8</pre>
-</div></div><p>The dedicated Activator will take care of discovering the presence of the <strong>org.webjars</strong>/<strong>swagger-ui</strong> bundle and configuring <strong>Swagger2Feature</strong>.</p><h2 id="Swagger2Feature-AutomaticUIActivation">Automatic UI Activation</h2><p>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.</p><p>For example, lets assume a JAX-RS endpoint is published at '<span>http://host:port/context/services/</span>'.</p><p>Open the browser and go to <span class="inline-comment-marker" data-ref="d7668130-e6ae-4083-a77a-cdfeb10de81e">'</span><span><span class="inline-comment-marker" data-ref="d7668130-e6ae-4083-a77a-cdfeb10de81e">http://host:port/context/services/</span></span><span class="inline-comment-marker" data-ref="d7668130-e6ae-4083-a77a-cdfeb10de81e">api-docs/?url=/swagger.json'</span> which will return a Swagger UI page.</
p><p>CXF Services page will also link to Swagger UI. Go to '<span>http://host:port/context/services/</span>services' and follow a Swagger link which will return a Swagger UI page.</p><p>See <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger2" rel="nofollow">samples/jax_rs/description_swagger2</a>, <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger2_web" rel="nofollow">samples/jax_rs/description_swagger2_web</a>, <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/spring_boot" rel="nofollow">samples/jax_rs/spring_boot</a> and <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/spring_boot_scan" rel="nofollow">samples/jax_r
s/spring_boot_scan</a> </p><p>Note that CXF OSGI endpoints can only depend on this feature starting from CXF 3.1.8.</p><h2 id="Swagger2Feature-UnpackingSwaggerUIresources">Unpacking Swagger UI resources</h2><p>Up until CXF 3.1.7 unpacking Swagger UI resources into the local folder was the only option. It is demoed in <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger2_spring" rel="nofollow">samples/jax_rs/description_swagger2_spring</a> and <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger2_osgi" rel="nofollow">samples/jax_rs/description_swagger2_osgi</a>.</p><p>In CXF 3.1.8: set Swagger2Feature 'supportSwaggerUi' property to 'false' to disable the automatic UI activation described in the previous section</p><h2 id="Swagger2Feature-ConfiguringSwaggerUI(3.2.7+)">Configuring Swagger
UI (3.2.7+)</h2><p>The <strong>Swagger2Feature</strong>  has a way to pre-configure certain  Swagger UI parameters (<a shape="rect" class="external-link" href="https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md" rel="nofollow">https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md</a>) through <strong><span class="blob-code-inner blob-code-marker-addition"><span class="pl-smi">SwaggerUiConfig</span></span></strong><span class="blob-code-inner blob-code-marker-addition">. The</span><strong><span class="blob-code-inner blob-code-marker-addition"> </span></strong>way it is implemented is by passing those parameters as a query string so the Swagger UI could adjust itself.</p><div class="confluence-information-macro confluence-information-macro-warning"><span class="aui-icon aui-icon-small aui-iconfont-error confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>Apache CXF prior to 3
.4.6 / 3.5.1 passed Swagger UI configuration (url, ...) as query parameters. Starting from Swagger UI <strong>4.1.3</strong>, 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 <code>queryConfigEnabled</code>  property of the <strong><span class="blob-code-inner blob-code-marker-addition"><span class="pl-smi">SwaggerUiConfig </span></span></strong><span class="blob-code-inner blob-code-marker-addition"><span class="pl-smi">to <code>true</code> .</span></span></p></div></div><h1 id="Swagger2Feature-ReverseProxy">Reverse Proxy</h1><p>Set a CXFServlet init parameter 'use-x-forwarded-headers' to 'true' if you access Swagger JSON and/or UI via the reverse proxy. If you use CXF SpringBoot starters then this property is prefixed with a "cxf.servlet.init.", "cxf.servlet.i
nit.use-x-forwarded-headers".</p><p>You may also need to set Swagger2Feature 'usePathBasedConfig' property to 'true' to prevent Swagger from caching the 'basePath' value.</p><h1 id="Swagger2Feature-ConvertingtoOpenAPIJSON">Converting to OpenAPI JSON</h1><p><a shape="rect" class="external-link" href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md" rel="nofollow">OpenAPI specification</a> has been released and the CXF team has started working on the new feature which will produce OpenAPI JSON with the help of the new core and jaxrs libraries being currently developed by the Swagger community.</p><p>In meantime, while the new feature development is taking place, one can experiment with converting the Swagger JSON produced by CXF Swagger2Feature into Open API JSON.</p><p>All what is needed is registering <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/description-swagger/src/main/java/org/apache/cxf/jaxrs/swagger/op
enapi/SwaggerToOpenApiConversionFilter.java" rel="nofollow">SwaggerToOpenApiConversionFilter</a> with the JAX-RS endpoint and requesting an "openapi.json" as opposed to "swagger.json". The filter will let Swagger2Feature generate JSON as usual and then convert the response to OpenAPI JSON if requested by the user or leave it intact otherwise. By issuing either "swagger.json" or "openapi.json" queries one can easily see the difference  between the two formats.</p><p>The cxf-rt-rs-json-basic dependency must be on the classpath as well.</p><p><span class="inline-comment-marker" data-ref="0182cc9a-9bcb-467e-ba6e-ecea683448e8">Note, <a shape="rect" class="external-link" href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md" rel="nofollow">OpenAPI JSON</a></span> (see also <a shape="rect" href="openapifeature.html">OpenApiFeature</a>) allows referring to its new "components/requestBodies" section from the multiple "requestBody" elements (which can be found
under the specific path/http verb sub-sections). By default the filter will instead inline the the "requestBody" definitions inside of "requestBody" elements, but one can experiment with referring to the "components/requestBodies" by <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/description-swagger/src/main/java/org/apache/cxf/jaxrs/swagger/openapi/OpenApiConfiguration.java" rel="nofollow">configuring</a> <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/description-swagger/src/main/java/org/apache/cxf/jaxrs/swagger/openapi/SwaggerToOpenApiConversionFilter.java#L63" rel="nofollow">the filter</a> to create the request bodies.   </p><p>The conversion filter is available starting from CXF 3.1.15 and 3.2.2</p><h1 id="Swagger2Feature-Samples">Samples</h1><p><span>CXF's distribution contains the following samples.</span></p><ul><li><a shape="rect" class="external-link" href="https://gith
ub.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger" rel="nofollow">samples/jax_rs/description_swagger</a>: Swagger 1.2 sample using SwaggerFeature programatically</li><li><a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger2" rel="nofollow">samples/jax_rs/description_swagger2</a>: Swagger 2.0 standalone sample using Swagger2Feature programatically</li><li><a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger2_spring" rel="nofollow">samples/jax_rs/description_swagger2_spring</a>: Swagger 2.0 standalone sample using Swagger2Feature using Spring</li><li><a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger2_web" rel="nofollow">samples/jax_rs/desc
ription_swagger2_web</a>: Swagger 2.0 web application sample using Swagger2Feature using Spring</li><li><a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger2_osgi" rel="nofollow">samples/jax_rs/description_swagger2_osgi</a>: Swagger 2.0 OSGi application sample using Swagger2Feature using Blueprint<br clear="none"><br clear="none"></li></ul><p><br clear="none"></p></div>
+</div></div><p>The dedicated Activator will take care of discovering the presence of the <strong>org.webjars</strong>/<strong>swagger-ui</strong> bundle and configuring <strong>Swagger2Feature</strong>.</p><h2 id="Swagger2Feature-AutomaticUIActivation">Automatic UI Activation</h2><p>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.</p><p>For example, lets assume a JAX-RS endpoint is published at '<span>http://host:port/context/services/</span>'.</p><p>Open the browser and go to <span class="inline-comment-marker" data-ref="d7668130-e6ae-4083-a77a-cdfeb10de81e">'</span><span><span class="inline-comment-marker" data-ref="d7668130-e6ae-4083-a77a-cdfeb10de81e">http://host:port/context/services/</span></span><span class="inline-comment-marker" data-ref="d7668130-e6ae-4083-a77a-cdfeb10de81e">api-docs/?url=/swagger.json'</span> which will return a Swagger UI page.</
p><p>CXF Services page will also link to Swagger UI. Go to '<span>http://host:port/context/services/</span>services' and follow a Swagger link which will return a Swagger UI page.</p><p>See <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger2" rel="nofollow">samples/jax_rs/description_swagger2</a>, <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger2_web" rel="nofollow">samples/jax_rs/description_swagger2_web</a>, <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/spring_boot" rel="nofollow">samples/jax_rs/spring_boot</a> and <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/spring_boot_scan" rel="nofollow">samples/jax_r
s/spring_boot_scan</a> </p><p>Note that CXF OSGI endpoints can only depend on this feature starting from CXF 3.1.8.</p><h2 id="Swagger2Feature-UnpackingSwaggerUIresources">Unpacking Swagger UI resources</h2><p>Up until CXF 3.1.7 unpacking Swagger UI resources into the local folder was the only option. It is demoed in <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger2_spring" rel="nofollow">samples/jax_rs/description_swagger2_spring</a> and <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger2_osgi" rel="nofollow">samples/jax_rs/description_swagger2_osgi</a>.</p><p>In CXF 3.1.8: set Swagger2Feature 'supportSwaggerUi' property to 'false' to disable the automatic UI activation described in the previous section</p><h2 id="Swagger2Feature-ConfiguringSwaggerUI(3.2.7+)">Configuring Swagger
UI (3.2.7+)</h2><p>The <strong>Swagger2Feature</strong>  has a way to pre-configure certain  Swagger UI parameters (<a shape="rect" class="external-link" rel="nofollow" href="https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md">https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md</a>) through <strong><span class="blob-code-inner blob-code-marker-addition"><span class="pl-smi">SwaggerUiConfig</span></span></strong><span class="blob-code-inner blob-code-marker-addition">. The</span><strong><span class="blob-code-inner blob-code-marker-addition"> </span></strong>way it is implemented is by passing those parameters as a query string so the Swagger UI could adjust itself.</p><div class="confluence-information-macro confluence-information-macro-warning"><span class="aui-icon aui-icon-small aui-iconfont-error confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>Apache CXF prior to 3
.4.6 / 3.5.1 passed Swagger UI configuration (url, ...) as query parameters. Starting from Swagger UI <strong>4.1.3</strong>, 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 <strong>turned on </strong>by setting <code>queryConfigEnabled</code>  property of the <strong><span class="blob-code-inner blob-code-marker-addition"><span class="pl-smi">SwaggerUiConfig </span></span></strong><span class="blob-code-inner blob-code-marker-addition"><span class="pl-smi">to <code>true</code> (the default value is <code>false</code> ).</span></span></p></div></div><h1 id="Swagger2Feature-ReverseProxy">Reverse Proxy</h1><p>Set a CXFServlet init parameter 'use-x-forwarded-headers' to 'true' if you access Swagger JSON and/or UI via the reverse proxy. If you use CXF SpringBoot starters then this prope
rty is prefixed with a "cxf.servlet.init.", "cxf.servlet.init.use-x-forwarded-headers".</p><p>You may also need to set Swagger2Feature 'usePathBasedConfig' property to 'true' to prevent Swagger from caching the 'basePath' value.</p><h1 id="Swagger2Feature-ConvertingtoOpenAPIJSON">Converting to OpenAPI JSON</h1><p><a shape="rect" class="external-link" href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md" rel="nofollow">OpenAPI specification</a> has been released and the CXF team has started working on the new feature which will produce OpenAPI JSON with the help of the new core and jaxrs libraries being currently developed by the Swagger community.</p><p>In meantime, while the new feature development is taking place, one can experiment with converting the Swagger JSON produced by CXF Swagger2Feature into Open API JSON.</p><p>All what is needed is registering <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/descrip
tion-swagger/src/main/java/org/apache/cxf/jaxrs/swagger/openapi/SwaggerToOpenApiConversionFilter.java" rel="nofollow">SwaggerToOpenApiConversionFilter</a> with the JAX-RS endpoint and requesting an "openapi.json" as opposed to "swagger.json". The filter will let Swagger2Feature generate JSON as usual and then convert the response to OpenAPI JSON if requested by the user or leave it intact otherwise. By issuing either "swagger.json" or "openapi.json" queries one can easily see the difference  between the two formats.</p><p>The cxf-rt-rs-json-basic dependency must be on the classpath as well.</p><p><span class="inline-comment-marker" data-ref="0182cc9a-9bcb-467e-ba6e-ecea683448e8">Note, <a shape="rect" class="external-link" href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md" rel="nofollow">OpenAPI JSON</a></span> (see also <a shape="rect" href="openapifeature.html">OpenApiFeature</a>) allows referring to its new "components/requestBodies" section fro
m the multiple "requestBody" elements (which can be found under the specific path/http verb sub-sections). By default the filter will instead inline the the "requestBody" definitions inside of "requestBody" elements, but one can experiment with referring to the "components/requestBodies" by <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/description-swagger/src/main/java/org/apache/cxf/jaxrs/swagger/openapi/OpenApiConfiguration.java" rel="nofollow">configuring</a> <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/description-swagger/src/main/java/org/apache/cxf/jaxrs/swagger/openapi/SwaggerToOpenApiConversionFilter.java#L63" rel="nofollow">the filter</a> to create the request bodies.   </p><p>The conversion filter is available starting from CXF 3.1.15 and 3.2.2</p><h1 id="Swagger2Feature-Samples">Samples</h1><p><span>CXF's distribution contains the following samples.</span></p><ul><l
i><a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger" rel="nofollow">samples/jax_rs/description_swagger</a>: Swagger 1.2 sample using SwaggerFeature programatically</li><li><a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger2" rel="nofollow">samples/jax_rs/description_swagger2</a>: Swagger 2.0 standalone sample using Swagger2Feature programatically</li><li><a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger2_spring" rel="nofollow">samples/jax_rs/description_swagger2_spring</a>: Swagger 2.0 standalone sample using Swagger2Feature using Spring</li><li><a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/de
scription_swagger2_web" rel="nofollow">samples/jax_rs/description_swagger2_web</a>: Swagger 2.0 web application sample using Swagger2Feature using Spring</li><li><a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger2_osgi" rel="nofollow">samples/jax_rs/description_swagger2_osgi</a>: Swagger 2.0 OSGi application sample using Swagger2Feature using Blueprint<br clear="none"><br clear="none"></li></ul><p><br clear="none"></p></div>
</div>
<!-- Content -->
</td>