Author: buildbot
Date: Tue Feb 15 02:43:00 2022
New Revision: 1078388
Log:
Production update by buildbot for cxf
Modified:
websites/production/cxf/content/cache/docs.pageCache
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/swagger2feature.html
==============================================================================
--- websites/production/cxf/content/docs/swagger2feature.html (original)
+++ websites/production/cxf/content/docs/swagger2feature.html Tue Feb 15
02:43:00 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.rbtoc1641921590637 {padding: 0px;}
-div.rbtoc1641921590637 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1641921590637 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1644892975954 {padding: 0px;}
+div.rbtoc1644892975954 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1644892975954 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1641921590637">
+/*]]>*/</style></p><div class="toc-macro rbtoc1644892975954">
<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><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 pref
ixed 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/description-swagge
r/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 from the multi
ple "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://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/description_s
wagger2_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></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>
<!-- Content -->
</td>
