Author: buildbot
Date: Sun Aug 28 15:42:53 2022
New Revision: 1080613
Log:
Production update by buildbot for cxf
Modified:
websites/production/cxf/content/cache/docs.pageCache
websites/production/cxf/content/docs/openapifeature.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 Sun Aug 28
15: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.rbtoc1661694167482 {padding: 0px;}
-div.rbtoc1661694167482 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1661694167482 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1661701368696 {padding: 0px;}
+div.rbtoc1661701368696 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1661701368696 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1661694167482">
+/*]]>*/</style></p><div class="toc-macro rbtoc1661701368696">
<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,7 +239,7 @@ 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">
+</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>
@@ -247,7 +247,12 @@ feature.setSecurityDefinitions(Collectio
</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></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 off </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 def
ault value is <code>false</code> and URLs are replaced dynamically). Please
notice that in this case the customized Swagger UI bundle is required since
<code>queryConfigEnabled</code>  property could only be set by altering
the distribution (<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>)<br
clear="none"></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 exam
ple, 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">
+</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 off </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 def
ault value is <code>false</code> and URLs are replaced dynamically). Please
notice that in this case the customized Swagger UI bundle is required since
<code>queryConfigEnabled</code>  property could only be set by altering
the distribution (<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>).
</span></span><span class="blob-code-inner blob-code-marker-addition"><span
class="pl-smi">The typical initialization for server-side dynamical URL
replacement  looks like this:<br clear="none"></span></span></p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default">new SwaggerUiConfig()
+ .url("/swagger.json")
+ ...
+ .queryConfigEnabled(false)</pre>
+</div></div></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);
