Modified: websites/production/cxf/content/docs/swagger2feature.html
==============================================================================
--- websites/production/cxf/content/docs/swagger2feature.html (original)
+++ websites/production/cxf/content/docs/swagger2feature.html Thu Sep 19
02:05:28 2019
@@ -34,6 +34,7 @@
<script src='/resources/highlighter/scripts/shCore.js'></script>
<script src='/resources/highlighter/scripts/shBrushJava.js'></script>
<script src='/resources/highlighter/scripts/shBrushXml.js'></script>
+<script src='/resources/highlighter/scripts/shBrushBash.js'></script>
<script>
SyntaxHighlighter.defaults['toolbar'] = false;
SyntaxHighlighter.all();
@@ -118,15 +119,15 @@ Apache CXF -- Swagger2Feature
<!-- Content -->
<div class="wiki-content">
<div id="ConfluenceContent"><h1
id="Swagger2Feature-Swagger2Feature">Swagger2Feature</h1><p><style
type="text/css">/*<![CDATA[*/
-div.rbtoc1537146966159 {padding: 0px;}
-div.rbtoc1537146966159 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1537146966159 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1568858552452 {padding: 0px;}
+div.rbtoc1568858552452 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1568858552452 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1537146966159">
+/*]]>*/</style></p><div class="toc-macro rbtoc1568858552452">
<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-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>
+<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>
-</div><p> </p><p>The CXF Swagger2Feature allows you to generate <a
shape="rect" class="external-link" href="http://swagger.io/specification/";
rel="nofollow">Swagger 2.0</a> documents from JAX-RS service endpoints
with a simple configuration.</p><p>For generating <a shape="rect"
class="external-link"
href="https://github.com/swagger-api/swagger-spec/blob/master/versions/1.2.md";
rel="nofollow">Swagger 1.2</a> documents, you can use SwaggerFeature instead of
Swagger2Feature (for CXF versions <= 3.1.x).</p><p>These features can be
configured programatically in Java or using Spring or Blueprint beans.</p><h1
id="Swagger2Feature-Setup">Setup</h1><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div><p><br clear="none"></p><p>The CXF Swagger2Feature allows you to
generate <a shape="rect" class="external-link"
href="http://swagger.io/specification/"; rel="nofollow">Swagger
2.0</a> documents from JAX-RS service endpoints with a simple
configuration.</p><p>For generating <a shape="rect" class="external-link"
href="https://github.com/swagger-api/swagger-spec/blob/master/versions/1.2.md";
rel="nofollow">Swagger 1.2</a> documents, you can use SwaggerFeature instead of
Swagger2Feature (for CXF versions <= 3.1.x).</p><p>These features can be
configured programatically in Java or using Spring or Blueprint beans.</p><h1
id="Swagger2Feature-Setup">Setup</h1><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.apache.cxf</groupId>
<artifactId>cxf-rt-rs-service-description-swagger</artifactId>
@@ -134,7 +135,7 @@ div.rbtoc1537146966159 li {margin-left:
</dependency>
</pre>
-</div></div><p>Note that a <strong>cxf-rt-rs-service-description</strong>
needs to be used if older CXF 3.1.x versions are used.</p><p> </p><h1
id="Swagger2Feature-Properties">Properties</h1><p><span style="line-height:
1.4285715;">The following optional parameters can be configured in
Swagger2Feature</span></p><p><span style="line-height: 1.4285715;">Note some
properties listed below are not available or used differently in
SwaggerFeature, as the corresponding properties are used differently in Swagger
2.0 and Swagger 1.2. Please refer to the corresponding Swagger documentation
for more information.)</span></p><div class="table-wrap"><table class="wrapped
confluenceTable"><colgroup span="1"><col span="1"><col span="1"><col
span="1"></colgroup><tbody><tr><th colspan="1" rowspan="1"
class="confluenceTh">Name</th><th colspan="1" rowspan="1"
class="confluenceTh">Description</th><th colspan="1" rowspan="1"
class="confluenceTh">Default</th></tr><tr><td colspan="1" rowspan="1" class=
"confluenceTd">basePath</td><td colspan="1" rowspan="1"
class="confluenceTd">the context root path<sup>+</sup></td><td colspan="1"
rowspan="1" class="confluenceTd">null</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">contact</td><td colspan="1" rowspan="1"
class="confluenceTd">the contact information<span>+</span></td><td colspan="1"
rowspan="1" class="confluenceTd">null (in CXF 3.1.x
"[email protected]")</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">description</td><td colspan="1" rowspan="1"
class="confluenceTd">the description<span>+</span></td><td colspan="1"
rowspan="1" class="confluenceTd">null (in CXF 3.1.x "The
Application")</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">filterClass</td><td colspan="1" rowspan="1"
class="confluenceTd">a security filter<span>+</span></td><td colspan="1"
rowspan="1" class="confluenceTd">null</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">host</td><td colspan="1" rowspan="1" class="
confluenceTd">the host and port<span>+</span></td><td colspan="1" rowspan="1"
class="confluenceTd">null</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">ignoreRoutes</td><td colspan="1" rowspan="1"
class="confluenceTd">excludes specific paths when scanning all resources (see
scanAllResources)<span>+</span><span>+</span></td><td colspan="1" rowspan="1"
class="confluenceTd">null</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">license</td><td colspan="1" rowspan="1"
class="confluenceTd">the license<span>+</span></td><td colspan="1" rowspan="1"
class="confluenceTd">"Apache 2.0 License"</td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd">licenceUrl</td><td colspan="1" rowspan="1"
class="confluenceTd">the license URL<span>+</span></td><td colspan="1"
rowspan="1" class="confluenceTd">"<span
class="nolink">http://www.apache.org/licenses/LICENSE-2.0.html</span>"</td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">prettyPrint</td><td colspan="1"
rowspan="1" class="confluenceTd">when generating swagger.json, pretty-print
the json document<span>+</span></td><td colspan="1" rowspan="1"
class="confluenceTd">false</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">resourcePackage</td><td colspan="1" rowspan="1"
class="confluenceTd">a list of comma separated package names where resources
must be scanned<span>+</span></td><td colspan="1" rowspan="1"
class="confluenceTd">a list of service classes configured at the
endpoint</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">runAsFilter</td><td colspan="1" rowspan="1"
class="confluenceTd">runs the feature as a filter</td><td colspan="1"
rowspan="1" class="confluenceTd">false</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">scan</td><td colspan="1" rowspan="1"
class="confluenceTd">generates the swagger documentation<span>+</span></td><td
colspan="1" rowspan="1" class="confluenceTd">true</td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd">sc
anAllResources</td><td colspan="1" rowspan="1" class="confluenceTd">scans all
resources including non-annotated JAX-RS
resources<span>+</span><span>+</span></td><td colspan="1" rowspan="1"
class="confluenceTd">false</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">schemes</td><td colspan="1" rowspan="1"
class="confluenceTd">the protocol schemes<span>+</span></td><td colspan="1"
rowspan="1" class="confluenceTd">null</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">termsOfServiceUrl</td><td colspan="1" rowspan="1"
class="confluenceTd">the terms of service URL<span>+</span></td><td colspan="1"
rowspan="1" class="confluenceTd">null</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">title</td><td colspan="1" rowspan="1"
class="confluenceTd">the title<span>+</span></td><td colspan="1" rowspan="1"
class="confluenceTd">null (in CXF 3.1.x "Sample REST
Application")</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">version</td><td colspan="1" r
owspan="1" class="confluenceTd">the version<span>+</span></td><td colspan="1"
rowspan="1" class="confluenceTd">null (in CXF 3.1.x "1.0.0")</td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><span class="blob-code-inner
blob-code-marker-addition">swaggerUiConfig</span></td><td colspan="1"
rowspan="1" class="confluenceTd">Swagger UI configuration</td><td colspan="1"
rowspan="1" class="confluenceTd">null</td></tr></tbody></table></div><p>Note:
those descriptions marked with <span>+ correspond to the properties
defined in Swagger's BeanConfig, and those marked
with <span>+</span><span>+ correspond to the properties defined in
Swagger's ReaderConfig.</span></span></p><h1
id="Swagger2Feature-ConfiguringfromCode">Configuring from
Code</h1><p> </p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
+</div></div><p>Note that a <strong>cxf-rt-rs-service-description</strong>
needs to be used if older CXF 3.1.x versions are used.</p><p><br
clear="none"></p><h1 id="Swagger2Feature-Properties">Properties</h1><p><span
style="line-height: 1.4285715;">The following optional parameters can be
configured in Swagger2Feature</span></p><p><span style="line-height:
1.4285715;">Note some properties listed below are not available or used
differently in SwaggerFeature, as the corresponding properties are used
differently in Swagger 2.0 and Swagger 1.2. Please refer to the corresponding
Swagger documentation for more information.)</span></p><div
class="table-wrap"><table class="wrapped confluenceTable"><colgroup
span="1"><col span="1"><col span="1"><col span="1"></colgroup><tbody><tr><th
colspan="1" rowspan="1" class="confluenceTh">Name</th><th colspan="1"
rowspan="1" class="confluenceTh">Description</th><th colspan="1" rowspan="1"
class="confluenceTh">Default</th></tr><tr><td colspan="1" rowspan
="1" class="confluenceTd">basePath</td><td colspan="1" rowspan="1"
class="confluenceTd">the context root path<sup>+</sup></td><td colspan="1"
rowspan="1" class="confluenceTd">null</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">contact</td><td colspan="1" rowspan="1"
class="confluenceTd">the contact information<span>+</span></td><td colspan="1"
rowspan="1" class="confluenceTd">null (in CXF 3.1.x
"[email protected]")</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">description</td><td colspan="1" rowspan="1"
class="confluenceTd">the description<span>+</span></td><td colspan="1"
rowspan="1" class="confluenceTd">null (in CXF 3.1.x "The
Application")</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">filterClass</td><td colspan="1" rowspan="1"
class="confluenceTd">a security filter<span>+</span></td><td colspan="1"
rowspan="1" class="confluenceTd">null</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">host</td><td colspan="1" rowspan=
"1" class="confluenceTd">the host and port<span>+</span></td><td colspan="1"
rowspan="1" class="confluenceTd">null</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">ignoreRoutes</td><td colspan="1" rowspan="1"
class="confluenceTd">excludes specific paths when scanning all resources (see
scanAllResources)<span>+</span><span>+</span></td><td colspan="1" rowspan="1"
class="confluenceTd">null</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">license</td><td colspan="1" rowspan="1"
class="confluenceTd">the license<span>+</span></td><td colspan="1" rowspan="1"
class="confluenceTd">"Apache 2.0 License"</td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd">licenceUrl</td><td colspan="1" rowspan="1"
class="confluenceTd">the license URL<span>+</span></td><td colspan="1"
rowspan="1" class="confluenceTd">"<span
class="nolink">http://www.apache.org/licenses/LICENSE-2.0.html</span>"</td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">prettyPrint</td><td c
olspan="1" rowspan="1" class="confluenceTd">when generating swagger.json,
pretty-print the json document<span>+</span></td><td colspan="1" rowspan="1"
class="confluenceTd">false</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">resourcePackage</td><td colspan="1" rowspan="1"
class="confluenceTd">a list of comma separated package names where resources
must be scanned<span>+</span></td><td colspan="1" rowspan="1"
class="confluenceTd">a list of service classes configured at the
endpoint</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">runAsFilter</td><td colspan="1" rowspan="1"
class="confluenceTd">runs the feature as a filter</td><td colspan="1"
rowspan="1" class="confluenceTd">false</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">scan</td><td colspan="1" rowspan="1"
class="confluenceTd">generates the swagger documentation<span>+</span></td><td
colspan="1" rowspan="1" class="confluenceTd">true</td></tr><tr><td colspan="1"
rowspan="1" class="confl
uenceTd">scanAllResources</td><td colspan="1" rowspan="1"
class="confluenceTd">scans all resources including non-annotated JAX-RS
resources<span>+</span><span>+</span></td><td colspan="1" rowspan="1"
class="confluenceTd">false</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">schemes</td><td colspan="1" rowspan="1"
class="confluenceTd">the protocol schemes<span>+</span></td><td colspan="1"
rowspan="1" class="confluenceTd">null</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">termsOfServiceUrl</td><td colspan="1" rowspan="1"
class="confluenceTd">the terms of service URL<span>+</span></td><td colspan="1"
rowspan="1" class="confluenceTd">null</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">title</td><td colspan="1" rowspan="1"
class="confluenceTd">the title<span>+</span></td><td colspan="1" rowspan="1"
class="confluenceTd">null (in CXF 3.1.x "Sample REST
Application")</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">version</td><td co
lspan="1" rowspan="1" class="confluenceTd">the version<span>+</span></td><td
colspan="1" rowspan="1" class="confluenceTd">null (in CXF 3.1.x
"1.0.0")</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><span
class="blob-code-inner
blob-code-marker-addition">swaggerUiConfig</span></td><td colspan="1"
rowspan="1" class="confluenceTd">Swagger UI configuration</td><td colspan="1"
rowspan="1" class="confluenceTd">null</td></tr></tbody></table></div><p>Note:
those descriptions marked with <span>+ correspond to the properties
defined in Swagger's BeanConfig, and those marked
with <span>+</span><span>+ correspond to the properties defined in
Swagger's ReaderConfig.</span></span></p><h1
id="Swagger2Feature-ConfiguringfromCode">Configuring from Code</h1><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">import
org.apache.cxf.frontend.ServerFactoryBean;
import org.apache.cxf.jaxrs.swagger.Swagger2Feature;
...
@@ -147,7 +148,7 @@ feature.setBasePath("/api");
// add this feature to the endpoint (e.g., to ServerFactoryBean's features)
ServerFactoryBean sfb = new ServerFactoryBean();
sfb.getFeatures().add(feature);</pre>
-</div></div><p> </p><h1
id="Swagger2Feature-ConfiguringinSpring">Configuring in
Spring</h1><p> </p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
+</div></div><p><br clear="none"></p><h1
id="Swagger2Feature-ConfiguringinSpring">Configuring in Spring</h1><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"><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";
@@ -182,7 +183,7 @@ sfb.getFeatures().add(feature);</pre>
</beans>
</pre>
-</div></div><p> </p><h1
id="Swagger2Feature-ConfiguringinBlueprint">Configuring in
Blueprint</h1><p> </p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
+</div></div><p><br clear="none"></p><h1
id="Swagger2Feature-ConfiguringinBlueprint">Configuring in Blueprint</h1><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"><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";
@@ -218,7 +219,7 @@ sfb.getFeatures().add(feature);</pre>
</jaxrs:server>
</blueprint>
 </pre>
-</div></div><h1
id="Swagger2Feature-ConfiguringinCXFNonSpringJaxrsServlet">Configuring in
CXFNonSpringJaxrsServlet</h1><p> </p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><h1
id="Swagger2Feature-ConfiguringinCXFNonSpringJaxrsServlet">Configuring in
CXFNonSpringJaxrsServlet</h1><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"><web-app>
<context-param>
<param-name>contextParam</param-name>
@@ -252,7 +253,7 @@ sfb.getFeatures().add(feature);</pre>
</servlet-mapping>
</web-app></pre>
-</div></div><h1 id="Swagger2Feature-New:ConfiguringfromPropertiesfile">New:
Configuring from Properties file</h1><p>Starting from CXF 3.1.13 and 3.2.0 it
is possible to configure Swagger2Feature with a Properties file.</p><p>For
example, while 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> demo configures the feature <a
shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/distribution/src/main/release/samples/jax_rs/spring_boot/src/main/java/sample/rs/service/SampleRestApplication.java#L54";
rel="nofollow">from the code</a>, a  <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_rs/spring_boot_scan</a> demo has it configured from
<a shape="rect" class="external-link" href="https://gith
ub.com/apache/cxf/blob/master/distribution/src/main/release/samples/jax_rs/spring_boot_scan/application/src/main/resources/swagger.properties"
rel="nofollow">the properties file</a>.</p><p>Default location for a
properties file is "<strong>/swagger.properties</strong>". Swagger2Feature will
pick it up if it is available, and the location can be overridden with a new
Swagger2Feature '<strong>swaggerPropertiesLocation</strong>'
property. </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="Swagger2Feature-EnablinginSpringBoot">Enabling in Spring Boot</h1><p>See <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
Swagger2Feature in a @Bean method 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"><span class="inline-comment-marker"
data-ref="95051881-e36a-491b-bc40-392fdb95feb0">samples/jax_rs/spring_boot_scan</span></a>
on how to auto-enable it.</p><p> </p><h1
id="Swagger2Feature-AccessingSwaggerDocuments">Accessing Swagger
Documents</h1><p>When Swagger is enabled by Swagger feature, the Swagger
documents will be available at the location URL constructed of the service
endpoint location followed by /swagger.json or /swagger.yaml.</p><p>For
example, lets assume a JAX-RS endpoint is published at
'http://host:port/context/services/' where 'context' is a web application
context, 
; "/services" is a servlet URL. In this case its Swagger documents are
available at 'http://host:port/context/services/swagger.json' and
'http://host:port/context/services/swagger.yaml'.</p><p>Starting from CXF 3.1.7
the CXF Services page will link to Swagger documents if Swagger2Feature is
active. </p><p>In the above example, go
to '<span>http://host:port/context/services/</span>services' and follow a
Swagger link which will return a Swagger JSON document.</p><p>If <a
shape="rect" class="external-link"
href="https://github.com/swagger-api/swagger-ui/blob/master/README.md#cors-support";
rel="nofollow">CORS support</a> is needed to access the definition from a
Swagger UI on another host, the <a shape="rect"
href="jax-rs-cors.html">CrossOriginResourceSharingFilter from
cxf-rt-rs-security-cors</a> can be added.</p><p> </p><h1
id="Swagger2Feature-EnablingSwaggerUI">Enabling Swagger UI</h1><p>First one
needs to add the following</p><div class="code panel pdl" style="border-
width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><h1 id="Swagger2Feature-New:ConfiguringfromPropertiesfile">New:
Configuring from Properties file</h1><p>Starting from CXF 3.1.13 and 3.2.0 it
is possible to configure Swagger2Feature with a Properties file.</p><p>For
example, while 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> demo configures the feature <a
shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/master/distribution/src/main/release/samples/jax_rs/spring_boot/src/main/java/sample/rs/service/SampleRestApplication.java#L54";
rel="nofollow">from the code</a>, a  <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_rs/spring_boot_scan</a> demo has it configured from
<a shape="rect" class="external-link" href="https://gith
ub.com/apache/cxf/blob/master/distribution/src/main/release/samples/jax_rs/spring_boot_scan/application/src/main/resources/swagger.properties"
rel="nofollow">the properties file</a>.</p><p>Default location for a
properties file is "<strong>/swagger.properties</strong>". Swagger2Feature will
pick it up if it is available, and the location can be overridden with a new
Swagger2Feature '<strong>swaggerPropertiesLocation</strong>'
property. </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="Swagger2Feature-EnablinginSpringBoot">Enabling in Spring Boot</h1><p>See <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
Swagger2Feature in a @Bean method 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"><span class="inline-comment-marker"
data-ref="95051881-e36a-491b-bc40-392fdb95feb0">samples/jax_rs/spring_boot_scan</span></a>
on how to auto-enable it.</p><p><br clear="none"></p><h1
id="Swagger2Feature-AccessingSwaggerDocuments">Accessing Swagger
Documents</h1><p>When Swagger is enabled by Swagger feature, the Swagger
documents will be available at the location URL constructed of the service
endpoint location followed by /swagger.json or /swagger.yaml.</p><p>For
example, lets assume a JAX-RS endpoint is published at
'http://host:port/context/services/' where 'context' is a web application co
ntext,  "/services" is a servlet URL. In this case its Swagger documents
are available at 'http://host:port/context/services/swagger.json' and
'http://host:port/context/services/swagger.yaml'.</p><p>Starting from CXF 3.1.7
the CXF Services page will link to Swagger documents if Swagger2Feature is
active. </p><p>In the above example, go
to '<span>http://host:port/context/services/</span>services' and follow a
Swagger link which will return a Swagger JSON document.</p><p>If <a
shape="rect" class="external-link"
href="https://github.com/swagger-api/swagger-ui/blob/master/README.md#cors-support";
rel="nofollow">CORS support</a> is needed to access the definition from a
Swagger UI on another host, the <a shape="rect"
href="jax-rs-cors.html">CrossOriginResourceSharingFilter from
cxf-rt-rs-security-cors</a> can be added.</p><p><br clear="none"></p><h1
id="Swagger2Feature-EnablingSwaggerUI">Enabling Swagger UI</h1><p>First one
needs to add the following</p><div class="code pan
el 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>
@@ -260,7 +261,9 @@ sfb.getFeatures().add(feature);</pre>
</dependency>
</pre>
-</div></div><p>The newest version 3.x of swagger-ui can also be used.</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_rs/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="S
wagger2Feature-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 sha
pe="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 prefixed with a
"cxf.servlet.init.", "cxf.servlet.init.use-x-forwarded-headers".</p><p>You may
also need to set Swagger2Feature 'usePathB
asedConfig' 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/openapi/SwaggerToOpenApiConversionFilter.java";
rel="nofollow">SwaggerToOpenApiConversion
Filter</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 in
line 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_swagger2_web";
rel="nofollow">samples/jax_rs/description_swagger2_web</a>: Swagger 2.0
web application sample using Swagger2Featur
e 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> </p></div>
+</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>
<!-- Content -->
</td>
