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 2018/04/08 17:57:17 UTC
svn commit: r1028072 - in /websites/production/cxf/content:
cache/docs.pageCache docs/openapifeature.html docs/swagger2feature.html
Author: buildbot
Date: Sun Apr 8 17:57:17 2018
New Revision: 1028072
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 Sun Apr 8 17:57:17 2018
@@ -118,21 +118,20 @@ Apache CXF -- OpenApiFeature
<td height="100%">
<!-- Content -->
<div class="wiki-content">
-<div id="ConfluenceContent"><h2 id="OpenApiFeature-/*<![CDATA[*/div.rbtoc1523206614834{padding:0px;}div.rbtoc1523206614834ul{list-style:disc;margin-left:0px;}div.rbtoc1523206614834li{margin-left:0px;padding-left:0px;}/*]]>*/#OpenApiFeature-Introduction#OpenApiFeature-IntroductionSetup#OpenA"><style type="text/css">/*<![CDATA[*/
-div.rbtoc1523206614834 {padding: 0px;}
-div.rbtoc1523206614834 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1523206614834 li {margin-left: 0px;padding-left: 0px;}
-
-/*]]>*/</style></h2><div class="toc-macro rbtoc1523206614834">
-<ul class="toc-indentation"><li><a shape="rect" href="#OpenApiFeature-"></a></li><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></ul>
-<ul><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></ul>
+<div id="ConfluenceContent"><h2 id="OpenApiFeature-/*<![CDATA[*/div.rbtoc1523210199567{padding:0px;}div.rbtoc1523210199567ul{list-style:disc;margin-left:0px;}div.rbtoc1523210199567li{margin-left:0px;padding-left:0px;}/*]]>*/#OpenApiFeature-Introduction#OpenApiFeature-IntroductionSetup#OpenA"><style type="text/css">/*<![CDATA[*/
+div.rbtoc1523210199567 {padding: 0px;}
+div.rbtoc1523210199567 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1523210199567 li {margin-left: 0px;padding-left: 0px;}
+
+/*]]>*/</style></h2><div class="toc-macro rbtoc1523210199567">
+<ul class="toc-indentation"><li><a shape="rect" href="#OpenApiFeature-"></a></li><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">En
abling Swagger UI</a></li><li><a shape="rect" href="#OpenApiFeature-Samples">Samples</a></li></ul>
</div><h2 id="OpenApiFeature-Introduction">Introduction</h2><p>The CXF <strong>OpenApiFeature</strong> allows you to generate <a shape="rect" class="external-link" href="https://github.com/OAI/OpenAPI-Specification/releases/tag/3.0.0" rel="nofollow">OpenAPI v3.0</a> documents from JAX-RS service endpoints with a simple configuration. This feature can be configured programmatically in Java or using Spring or Blueprint beans.</p><h2 id="OpenApiFeature-Setup">Setup</h2><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"><dependency>
<groupId>org.apache.cxf</groupId>
<artifactId>cxf-rt-rs-service-description-openapi-v3</artifactId>
<version>3.2.4</version>
</dependency></pre>
-</div></div><p>The <strong>cxf-rt-rs-service-description-openapi-v3</strong> is only available in <strong>3.2.x</strong> and above due to Java 8 baseline. For older releases, as well as for the users of older Swagger specifications 1.x/2.x, the is dedicated converter provided: <span class="confluence-link">org.apache.cxf.jaxrs.swagger.openapi.SwaggerToOpenApiConversionFilter</span>.</p><h2 id="OpenApiFeature-Properties">Properties</h2><p><span>The following optional parameters can be configured in <strong>OpenApiFeature</strong>. Note that although there are some similarities with Swagger specifications 1.x/2.x, <a shape="rect" class="external-link" href="https://github.com/OAI/OpenAPI-Specification/releases/tag/3.0.0" rel="nofollow">OpenAPI v3.0</a> is a significant revamp of the specification (in a good sense of it).</span></p><div class="table-wrap"><table class="confluenceTable"><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 value (if applicable)</th><th colspan="1" rowspan="1" class="confluenceTh">Sample value (if applicable)</th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">securityDefinitions</td><td colspan="1" rowspan="1" class="confluenceTd">a list of security definitions<strong>*</strong></td><td colspan="1" rowspan="1" class="confluenceTd">null</td><td colspan="1" rowspan="1" class="confluenceTd"><p>["basicAuth" -> new SecurityScheme().type(Type.HTTP))]</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">customizer</td><td colspan="1" rowspan="1" class="confluenceTd">the customizer class instance</td><td colspan="1" rowspan="1" class="confluenceTd">null</td><td colspan="1" rowspan="1" class="confluenceTd">new OpenApiCustomizer()</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">swaggerUiMavenGroupAndArtifact</td><td colspan="1" rowspan="1" class="confluenceTd">t
he Maven artifacts to pinpoint SwaggerUI</td><td colspan="1" rowspan="1" class="confluenceTd">null</td><td colspan="1" rowspan="1" class="confluenceTd">"org.webjars.swagger-ui'</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">swaggerUiVersion</td><td colspan="1" rowspan="1" class="confluenceTd">the version of SwaggerUI</td><td colspan="1" rowspan="1" class="confluenceTd">null</td><td colspan="1" rowspan="1" class="confluenceTd">"3.13.0"</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">supportSwaggerUi</td><td colspan="1" rowspan="1" class="confluenceTd">turns on/off SwaggerUI support</td><td colspan="1" rowspan="1" class="confluenceTd"><strong>false</strong></td><td colspan="1" rowspan="1" class="confluenceTd">false</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">filterClass</td><td colspan="1" rowspan="1" class="confluenceTd">a security filter<strong>*</strong><strong>*</strong></td><td colspan="1" rowspan="1" class="confluenceTd">null</td><t
d colspan="1" rowspan="1" class="confluenceTd">"com.example.filter.SampleFilter"</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">resourceClasses</td><td colspan="1" rowspan="1" class="confluenceTd">a list of resource classes which must be scanned<strong>*</strong><strong>*</strong></td><td colspan="1" rowspan="1" class="confluenceTd">null</td><td colspan="1" rowspan="1" class="confluenceTd">["com.example.rest.SampleResource"]</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">resourcePackages</td><td colspan="1" rowspan="1" class="confluenceTd">a list of package names where resources must be scanned<strong>*</strong><strong>*</strong></td><td colspan="1" rowspan="1" class="confluenceTd">null</td><td colspan="1" rowspan="1" class="confluenceTd">["com.example.rest"]</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">ignoredRoutes</td><td colspan="1" rowspan="1" class="confluenceTd">excludes specific paths when scanning all resources (see scanAllReso
urces)<span><strong>*</strong><strong>*</strong></span></td><td colspan="1" rowspan="1" class="confluenceTd">null</td><td colspan="1" rowspan="1" class="confluenceTd">["/api/test"]</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">prettyPrint</td><td colspan="1" rowspan="1" class="confluenceTd">when generating openapi.json, pretty-print the JSON document<span><strong>*</strong><strong>*</strong></span></td><td colspan="1" rowspan="1" class="confluenceTd"><strong>true</strong></td><td colspan="1" rowspan="1" class="confluenceTd">true</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"><strong>false</strong></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">Scan all JAX-RS resources automatic
ally</td><td colspan="1" rowspan="1" class="confluenceTd"><strong>true</strong></td><td colspan="1" rowspan="1" class="confluenceTd">true</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">readAllResources</td><td colspan="1" rowspan="1" class="confluenceTd"><span>Read all operations also with no @Operation<strong>*</strong><strong>*</strong></span><span> </span></td><td colspan="1" rowspan="1" class="confluenceTd"><strong>true</strong></td><td colspan="1" rowspan="1" class="confluenceTd">true</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><strong>*</strong></span></td><td colspan="1" rowspan="1" class="confluenceTd">null</td><td colspan="1" rowspan="1" class="confluenceTd">null</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">licenseUrl</td><td colspan="1" rowspan="1" class="confluenceTd">the license URL<strong>*</strong></td><td colspan="
1" rowspan="1" class="confluenceTd">null</td><td colspan="1" rowspan="1" class="confluenceTd">"<span class="nolink"><a shape="rect" class="external-link" href="http://www.apache.org/licenses/LICENSE-2.0.html">http://www.apache.org/licenses/LICENSE-2.0.html</a></span>"</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">license</td><td colspan="1" rowspan="1" class="confluenceTd">the license<span><strong>*</strong></span></td><td colspan="1" rowspan="1" class="confluenceTd">null</td><td colspan="1" rowspan="1" class="confluenceTd">"Apache 2.0 License"</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">contactUrl</td><td colspan="1" rowspan="1" class="confluenceTd">the contact link<strong>*</strong></td><td colspan="1" rowspan="1" class="confluenceTd">null</td><td colspan="1" rowspan="1" class="confluenceTd">null</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">contactEmail</td><td colspan="1" rowspan="1" class="confluenceTd">the contact email<strong>
*</strong></td><td colspan="1" rowspan="1" class="confluenceTd">null</td><td colspan="1" rowspan="1" class="confluenceTd">"users@<a shape="rect" href="http://cxf.apache.org">cxf.apache.org</a>"</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">contactName</td><td colspan="1" rowspan="1" class="confluenceTd">the contact name<strong>*</strong></td><td colspan="1" rowspan="1" class="confluenceTd">null</td><td colspan="1" rowspan="1" class="confluenceTd">null</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">description</td><td colspan="1" rowspan="1" class="confluenceTd">the description<span><strong>*</strong></span></td><td colspan="1" rowspan="1" class="confluenceTd">null</td><td colspan="1" rowspan="1" class="confluenceTd">"The Sample REST Application with OpenAPI integration"</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">title</td><td colspan="1" rowspan="1" class="confluenceTd">the title<span><strong>*</strong></span></td><td colspan="1" row
span="1" class="confluenceTd">null</td><td colspan="1" rowspan="1" class="confluenceTd">"Sample REST Application"</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">version</td><td colspan="1" rowspan="1" class="confluenceTd">the version<span><strong>*</strong></span></td><td colspan="1" rowspan="1" class="confluenceTd">null</td><td colspan="1" rowspan="1" class="confluenceTd">"1.0.0"</td></tr></tbody></table></div><p><span><strong>*</strong> - t<span>he properties are defined in the OpenAPI class</span></span></p><p><span><span> </span><span><strong>*</strong></span><span><strong>*</strong></span> - <span>t<span>he properties are defined in the SwaggerConfiguration class</span></span></span></p><h2 id="OpenApiFeature-ConfiguringfromCode">Configuring from Code</h2><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>The <strong>cxf-rt-rs-service-description-openapi-v3</strong> is only available in <strong>3.2.x</strong> and above due to Java 8 baseline. For older releases, as well as for the users of older Swagger specifications 1.x/2.x, there is a dedicated converter provided: <span class="confluence-link"><a shape="rect" href="https://cwiki.apache.org/confluence/display/CXF20DOC/Swagger2Feature">org.apache.cxf.jaxrs.swagger.openapi.SwaggerToOpenApiConversionFilte</a>r</span>.</p><h2 id="OpenApiFeature-Properties">Properties</h2><p><span>The following optional parameters can be configured in <strong>OpenApiFeature</strong>. Note that although there are some similarities with Swagger specifications 1.x/2.x, <a shape="rect" class="external-link" href="https://github.com/OAI/OpenAPI-Specification/releases/tag/3.0.0" rel="nofollow">OpenAPI v3.0</a> is a significant revamp of the specification (in a good sense of it).</span></p><div class="table-wrap"><table class="confluenceTab
le"><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 value (if applicable)</th><th colspan="1" rowspan="1" class="confluenceTh">Sample value (if applicable)</th><th colspan="1" rowspan="1" class="confluenceTh"> </th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">configLocation</td><td colspan="1" rowspan="1" class="confluenceTd"><p>the OpenAPI configuration location</p></td><td colspan="1" rowspan="1" class="confluenceTd">null</td><td colspan="1" rowspan="1" class="confluenceTd">/openapi-configuration.yml</td><td colspan="1" rowspan="1" class="confluenceTd"> </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">propertiesLocation</td><td colspan="1" rowspan="1" class="confluenceTd">the properties file location</td><td colspan="1" rowspan="1" class="confluenceTd">/swagger.properties</td><td colspan="1" rowspan="1"
class="confluenceTd"> /swagger.properties</td><td colspan="1" rowspan="1" class="confluenceTd"> </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">securityDefinitions</td><td colspan="1" rowspan="1" class="confluenceTd">a list of security definitions<strong>*</strong></td><td colspan="1" rowspan="1" class="confluenceTd">null</td><td colspan="1" rowspan="1" class="confluenceTd"><p>["basicAuth" -> new SecurityScheme().type(Type.HTTP))]</p></td><td colspan="1" rowspan="1" class="confluenceTd"> </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">customizer</td><td colspan="1" rowspan="1" class="confluenceTd">the customizer class instance</td><td colspan="1" rowspan="1" class="confluenceTd">null</td><td colspan="1" rowspan="1" class="confluenceTd">new OpenApiCustomizer()</td><td colspan="1" rowspan="1" class="confluenceTd"> </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">swaggerUiMavenGroupAndArtifact</td><td colspan="1" rowspa
n="1" class="confluenceTd">the Maven artifacts to pinpoint SwaggerUI</td><td colspan="1" rowspan="1" class="confluenceTd">null</td><td colspan="1" rowspan="1" class="confluenceTd">"org.webjars.swagger-ui'</td><td colspan="1" rowspan="1" class="confluenceTd"> </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">swaggerUiVersion</td><td colspan="1" rowspan="1" class="confluenceTd">the version of SwaggerUI</td><td colspan="1" rowspan="1" class="confluenceTd">null</td><td colspan="1" rowspan="1" class="confluenceTd">"3.13.0"</td><td colspan="1" rowspan="1" class="confluenceTd"> </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">supportSwaggerUi</td><td colspan="1" rowspan="1" class="confluenceTd">turns on/off SwaggerUI support</td><td colspan="1" rowspan="1" class="confluenceTd"><strong>null (== true)</strong></td><td colspan="1" rowspan="1" class="confluenceTd">true</td><td colspan="1" rowspan="1" class="confluenceTd"> </td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd">filterClass</td><td colspan="1" rowspan="1" class="confluenceTd">a security filter<strong>*</strong><strong>*</strong></td><td colspan="1" rowspan="1" class="confluenceTd">null</td><td colspan="1" rowspan="1" class="confluenceTd">"com.example.filter.SampleFilter"</td><td colspan="1" rowspan="1" class="confluenceTd"> </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">resourceClasses</td><td colspan="1" rowspan="1" class="confluenceTd">a list of resource classes which must be scanned<strong>*</strong><strong>*</strong></td><td colspan="1" rowspan="1" class="confluenceTd">null</td><td colspan="1" rowspan="1" class="confluenceTd">["com.example.rest.SampleResource"]</td><td colspan="1" rowspan="1" class="confluenceTd"> </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">resourcePackages</td><td colspan="1" rowspan="1" class="confluenceTd">a list of package names where resources must be scanned<strong>*</strong><strong>*</s
trong></td><td colspan="1" rowspan="1" class="confluenceTd">null</td><td colspan="1" rowspan="1" class="confluenceTd">["com.example.rest"]</td><td colspan="1" rowspan="1" class="confluenceTd"> </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">ignoredRoutes</td><td colspan="1" rowspan="1" class="confluenceTd">excludes specific paths when scanning all resources (see scanAllResources)<span><strong>*</strong><strong>*</strong></span></td><td colspan="1" rowspan="1" class="confluenceTd">null</td><td colspan="1" rowspan="1" class="confluenceTd">["/api/test"]</td><td colspan="1" rowspan="1" class="confluenceTd"> </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">prettyPrint</td><td colspan="1" rowspan="1" class="confluenceTd">when generating openapi.json, pretty-print the JSON document<span><strong>*</strong><strong>*</strong></span></td><td colspan="1" rowspan="1" class="confluenceTd"><strong>true</strong></td><td colspan="1" rowspan="1" class="confluenc
eTd">true</td><td colspan="1" rowspan="1" class="confluenceTd"> </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"><strong>false</strong></td><td colspan="1" rowspan="1" class="confluenceTd">false</td><td colspan="1" rowspan="1" class="confluenceTd"> </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">scan</td><td colspan="1" rowspan="1" class="confluenceTd">Scan all JAX-RS resources automatically</td><td colspan="1" rowspan="1" class="confluenceTd"><strong>true</strong></td><td colspan="1" rowspan="1" class="confluenceTd">true</td><td colspan="1" rowspan="1" class="confluenceTd"> </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">readAllResources</td><td colspan="1" rowspan="1" class="confluenceTd"><span>Read all operations also with no @Operation<strong>*</strong><strong>*</strong></span
><span> </span></td><td colspan="1" rowspan="1" class="confluenceTd"><strong>true</strong></td><td colspan="1" rowspan="1" class="confluenceTd">true</td><td colspan="1" rowspan="1" class="confluenceTd"> </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><strong>*</strong></span></td><td colspan="1" rowspan="1" class="confluenceTd">null</td><td colspan="1" rowspan="1" class="confluenceTd">null</td><td colspan="1" rowspan="1" class="confluenceTd"> </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">licenseUrl</td><td colspan="1" rowspan="1" class="confluenceTd">the license URL<strong>*</strong></td><td colspan="1" rowspan="1" class="confluenceTd">null</td><td colspan="1" rowspan="1" class="confluenceTd">"<span class="nolink"><a shape="rect" class="external-link" href="http://www.apache.org/licenses/LICENSE-2.0.html">http://www.apache.org/licenses/L
ICENSE-2.0.html</a></span>"</td><td colspan="1" rowspan="1" class="confluenceTd"> </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">license</td><td colspan="1" rowspan="1" class="confluenceTd">the license<span><strong>*</strong></span></td><td colspan="1" rowspan="1" class="confluenceTd">null</td><td colspan="1" rowspan="1" class="confluenceTd">"Apache 2.0 License"</td><td colspan="1" rowspan="1" class="confluenceTd"> </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">contactUrl</td><td colspan="1" rowspan="1" class="confluenceTd">the contact link<strong>*</strong></td><td colspan="1" rowspan="1" class="confluenceTd">null</td><td colspan="1" rowspan="1" class="confluenceTd">null</td><td colspan="1" rowspan="1" class="confluenceTd"> </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">contactEmail</td><td colspan="1" rowspan="1" class="confluenceTd">the contact email<strong>*</strong></td><td colspan="1" rowspan="1" class="confluenceT
d">null</td><td colspan="1" rowspan="1" class="confluenceTd">"users@<a shape="rect" href="http://cxf.apache.org">cxf.apache.org</a>"</td><td colspan="1" rowspan="1" class="confluenceTd"> </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">contactName</td><td colspan="1" rowspan="1" class="confluenceTd">the contact name<strong>*</strong></td><td colspan="1" rowspan="1" class="confluenceTd">null</td><td colspan="1" rowspan="1" class="confluenceTd">null</td><td colspan="1" rowspan="1" class="confluenceTd"> </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">description</td><td colspan="1" rowspan="1" class="confluenceTd">the description<span><strong>*</strong></span></td><td colspan="1" rowspan="1" class="confluenceTd">null</td><td colspan="1" rowspan="1" class="confluenceTd">"The Sample REST Application with OpenAPI integration"</td><td colspan="1" rowspan="1" class="confluenceTd"> </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">titl
e</td><td colspan="1" rowspan="1" class="confluenceTd">the title<span><strong>*</strong></span></td><td colspan="1" rowspan="1" class="confluenceTd">null</td><td colspan="1" rowspan="1" class="confluenceTd">"Sample REST Application"</td><td colspan="1" rowspan="1" class="confluenceTd"> </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">version</td><td colspan="1" rowspan="1" class="confluenceTd">the version<span><strong>*</strong></span></td><td colspan="1" rowspan="1" class="confluenceTd">null</td><td colspan="1" rowspan="1" class="confluenceTd">"1.0.0"</td><td colspan="1" rowspan="1" class="confluenceTd"> </td></tr></tbody></table></div><p><span><strong>*</strong> - t<span>he properties are defined in the OpenAPI class</span></span></p><p><span><span> </span><span><strong>*</strong></span><span><strong>*</strong></span> - <span>t<span>he properties are defined in the SwaggerConfiguration class</span></span></span></p><h2 id="OpenApiFeature-Configuri
ngfromCode">Configuring from Code</h2><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">import org.apache.cxf.jaxrs.openapi.OpenApiFeature;
import io.swagger.v3.oas.models.security.SecurityScheme;
import io.swagger.v3.oas.models.security.SecurityScheme.Type;
@@ -144,7 +143,7 @@ feature.setContactEmail("cxf@apache.org"
feature.setLicense("Apache 2.0 License");
feature.setLicenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html");
feature.setSecurityDefinitions(Collections.singletonMap("basicAuth",new SecurityScheme().type(Type.HTTP)));</pre>
-</div></div><p> </p><h1 id="OpenApiFeature-ConfiguringfromSpring">Configuring from Spring</h1><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p> </p><h2 id="OpenApiFeature-ConfiguringfromSpring">Configuring from Spring</h2><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"><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"
@@ -156,7 +155,7 @@ feature.setSecurityDefinitions(Collectio
<bean id="jsonProvider" class="com.fasterxml.jackson.jaxrs.json.JacksonJsonProvider" />
<!-- Application resources -->
- <bean id="sampleResource" class="demo.jaxrs.swagger.server.Sample" />
+ <bean id="sampleResource" class="demo.jaxrs.openapi.server.Sample" />
<!-- CXF OpenApiFeature -->
<bean id="openApiFeature" class="org.apache.cxf.jaxrs.openapi.OpenApiFeature">
@@ -177,7 +176,7 @@ feature.setSecurityDefinitions(Collectio
</jaxrs:features>
</jaxrs:server>
</beans></pre>
-</div></div><p> </p><h1 id="OpenApiFeature-ConfiguringinBlueprint">Configuring in Blueprint</h1><p>In case of Apache Karaf, the <a shape="rect" class="external-link" href="https://github.com/OAI/OpenAPI-Specification/releases/tag/3.0.0" rel="nofollow">OpenAPI v3.0</a> integration is available as <strong>cxf-rs-description-openapi-v3</strong> feature.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p> </p><h2 id="OpenApiFeature-ConfiguringinBlueprint">Configuring in Blueprint</h2><p>In case of Apache Karaf, the <a shape="rect" class="external-link" href="https://github.com/OAI/OpenAPI-Specification/releases/tag/3.0.0" rel="nofollow">OpenAPI v3.0</a> integration is available as <strong>cxf-rs-description-openapi-v3</strong> feature.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">feature:install cxf-rs-description-openapi-v3</pre>
</div></div><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"><blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
@@ -192,7 +191,7 @@ feature.setSecurityDefinitions(Collectio
<bean id="jsonProvider" class="com.fasterxml.jackson.jaxrs.json.JacksonJsonProvider" />
<!-- Application resources -->
- <bean id="sampleResource" class="demo.jaxrs.swagger.server.Sample" />
+ <bean id="sampleResource" class="demo.jaxrs.openapi.server.Sample" />
<!-- CXF OpenApiFeature -->
@@ -214,7 +213,7 @@ feature.setSecurityDefinitions(Collectio
</jaxrs:features>
</jaxrs:server>
</blueprint></pre>
-</div></div><p> </p><h1 id="OpenApiFeature-ConfiguringinCXFNonSpringJaxrsServlet">Configuring in CXFNonSpringJaxrsServlet</h1><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p> </p><h2 id="OpenApiFeature-ConfiguringinCXFNonSpringJaxrsServlet">Configuring in CXFNonSpringJaxrsServlet</h2><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"><web-app>
<context-param>
<param-name>contextParam</param-name>
@@ -242,7 +241,13 @@ feature.setSecurityDefinitions(Collectio
</servlet-mapping>
</web-app></pre>
-</div></div><p> </p><p><span><span><span><br clear="none"></span></span></span></p></div>
+</div></div><h2 id="OpenApiFeature-ConfiguringfromPropertyfiles">Configuring from Property files</h2><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. Please take into account that there is a certain level of the overlap between both.</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 prop
erties: 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><h2 id="OpenApiFeature-SpringBootAutoConfiguration">Spring Boot Auto Configuration</h2><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 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> on how to auto-enable it.</p><h2 id="OpenApiFeature-EnablingSwaggerUI">Enabling Swagger UI</h2><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> </p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"><dependency>
+ <groupId>org.webjars</groupId>
+ <artifactId>swagger-ui</artifactId>
+ <version>3.13.0</version>
+</dependency></pre>
+</div></div><p> </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 integration ple
ase set<strong> 'supportSwaggerUi'</strong> property to "<strong>false</strong>".</p><h2 id="OpenApiFeature-Samples">Samples</h2><p><span>CXF's distribution contains the following samples.</span></p><ul style="list-style-type: square;"><li><span><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>: the <a shape="rect" class="external-link" href="https://github.com/OAI/OpenAPI-Specification/releases/tag/3.0.0" rel="nofollow">OpenAPI v3.0</a> standalone sample using OpenApiFeature programmatically</span></li><li><span><span><a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_openapi_v3_osgi" rel="nofollow">samples/jax_rs/description_openapi_v3_osgi</a>: the</span> </span><span><a shape="rect" class="external-link" href="https://github
.com/OAI/OpenAPI-Specification/releases/tag/3.0.0" rel="nofollow">OpenAPI v3.0</a> </span>OSGi application sample using <span>OpenApiFeature </span>using Blueprint</li></ul></div></div>
</div>
<!-- Content -->
</td>
Modified: websites/production/cxf/content/docs/swagger2feature.html
==============================================================================
--- websites/production/cxf/content/docs/swagger2feature.html (original)
+++ websites/production/cxf/content/docs/swagger2feature.html Sun Apr 8 17:57:17 2018
@@ -118,11 +118,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.rbtoc1518605810440 {padding: 0px;}
-div.rbtoc1518605810440 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1518605810440 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1523210198632 {padding: 0px;}
+div.rbtoc1523210198632 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1523210198632 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1518605810440">
+/*]]>*/</style></p><div class="toc-macro rbtoc1523210198632">
<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></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>
@@ -252,7 +252,7 @@ import org.apache.cxf.jaxrs.swagger.Swag
</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 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> 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 'ht
tp://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 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"><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">
<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;"><dependency>
<groupId>org.webjars</groupId>
<artifactId>swagger-ui</artifactId>
@@ -260,7 +260,7 @@ import org.apache.cxf.jaxrs.swagger.Swag
</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>http://host:port/context/services/</span>api-docs?/url=/swagger.json' 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>,
60;<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="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/mas
ter/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><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 'usePathBasedConfig' property to 'true' to prevent Swagger from caching the 'basePath' value.</p><h1 id="Sw
agger2Feature-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">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>Note, OpenAPI JSON 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="exte
rnal-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 progra
matically</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 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> </p></div>
+</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><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 Spri
ngBoot 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 '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/apach
e/cxf/blob/master/rt/rs/description-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, OpenAPI JSON</span> 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" definition
s 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 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> </p></div>
</div>
<!-- Content -->
</td>