Author: buildbot Date: Sat Sep 7 19:56:43 2019 New Revision: 1049784 Log: Production update by buildbot for cxf
Modified: websites/production/cxf/content/cache/docs.pageCache websites/production/cxf/content/docs/openapifeature.html Modified: websites/production/cxf/content/cache/docs.pageCache ============================================================================== Binary files - no diff available. Modified: websites/production/cxf/content/docs/openapifeature.html ============================================================================== --- websites/production/cxf/content/docs/openapifeature.html (original) +++ websites/production/cxf/content/docs/openapifeature.html Sat Sep 7 19:56:43 2019 @@ -119,11 +119,11 @@ Apache CXF -- OpenApiFeature <!-- Content --> <div class="wiki-content"> <div id="ConfluenceContent"><p><style type="text/css">/*<![CDATA[*/ -div.rbtoc1543773415480 {padding: 0px;} -div.rbtoc1543773415480 ul {list-style: disc;margin-left: 0px;} -div.rbtoc1543773415480 li {margin-left: 0px;padding-left: 0px;} +div.rbtoc1567886164435 {padding: 0px;} +div.rbtoc1567886164435 ul {list-style: disc;margin-left: 0px;} +div.rbtoc1567886164435 li {margin-left: 0px;padding-left: 0px;} -/*]]>*/</style></p><div class="toc-macro rbtoc1543773415480"> +/*]]>*/</style></p><div class="toc-macro rbtoc1567886164435"> <ul class="toc-indentation"><li><a shape="rect" href="#OpenApiFeature-Introduction">Introduction</a></li><li><a shape="rect" href="#OpenApiFeature-Setup">Setup</a></li><li><a shape="rect" href="#OpenApiFeature-Properties">Properties</a></li><li><a shape="rect" href="#OpenApiFeature-ConfiguringfromCode">Configuring from Code</a></li><li><a shape="rect" href="#OpenApiFeature-ConfiguringfromSpring">Configuring from Spring</a></li><li><a shape="rect" href="#OpenApiFeature-ConfiguringinBlueprint">Configuring in Blueprint</a></li><li><a shape="rect" href="#OpenApiFeature-ConfiguringinCXFNonSpringJaxrsServlet">Configuring in CXFNonSpringJaxrsServlet</a></li><li><a shape="rect" href="#OpenApiFeature-ConfiguringfromPropertyfiles">Configuring from Property files</a></li><li><a shape="rect" href="#OpenApiFeature-SpringBootAutoConfiguration">Spring Boot Auto Configuration</a></li><li><a shape="rect" href="#OpenApiFeature-EnablingSwaggerUI">Enabling Swagger UI</a></li><li><a shape="rect" href="# OpenApiFeature-ConfiguringSwaggerUI(3.2.7+)">Configuring Swagger UI (3.2.7+)</a></li><li><a shape="rect" href="#OpenApiFeature-OpenApiFeature-UsingMultipleServerEndpoints(3.3.0+)UsingMultipleServerEndpoints(3.3.0+)">Using Multiple Server Endpoints (3.3.0+)</a></li><li><a shape="rect" href="#OpenApiFeature-Samples">Samples</a></li></ul> </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"><dependency> @@ -136,7 +136,7 @@ div.rbtoc1543773415480 li {margin-left: openapi-configuration.json openapi.yaml openapi.json</pre> -</div></div></td><td colspan="1" rowspan="1" class="confluenceTd">true</td><td colspan="1" rowspan="1" class="confluenceTd">true</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></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">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></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>null (== true)</strong></td><td colspan="1" rowspan="1" class="confluenceT d">true</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></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 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></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 automatically</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="c onfluenceTd">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="c onfluenceTd">"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" rowspan="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><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><td colspan="1" rowspan="1" class="confluenceTd">new <span class ="blob-code-inner blob-code-marker-addition"><span class="pl-smi">SwaggerUiConfig</span>().url("/openapi.json")</span></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">useContextBasedConfig</td><td colspan="1" rowspan="1" class="confluenceTd">If set, the unique Context Id is going to be generated for each OpenApiContext instance (see please <a shape="rect" href="openapifeature.html">Using Multiple Server Endpoints</a>). Also, you very likely may want to set <strong>scan</strong> property to <strong>false</strong>.</td><td colspan="1" rowspan="1" class="confluenceTd"><strong>false</strong></td><td colspan="1" rowspan="1" class="confluenceTd">false</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><h 2 id="OpenApiFeature-ConfiguringfromCode">Configuring from Code</h2><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> +</div></div></td><td colspan="1" rowspan="1" class="confluenceTd">true</td><td colspan="1" rowspan="1" class="confluenceTd">true</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></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">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></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>null (== true)</strong></td><td colspan="1" rowspan="1" class="confluenceT d">true</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></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 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></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 automatically</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="c onfluenceTd">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="c onfluenceTd">"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" rowspan="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><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><td colspan="1" rowspan="1" class="confluenceTd">new <span class ="blob-code-inner blob-code-marker-addition"><span class="pl-smi">SwaggerUiConfig</span>().url("/openapi.json")</span></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">useContextBasedConfig</td><td colspan="1" rowspan="1" class="confluenceTd">If set, the unique Context Id is going to be generated for each OpenApiContext instance (see please <a shape="rect" href="openapifeature.html">Using Multiple Server Endpoints</a>). Also, you very likely may want to set <strong>scan</strong> property to <strong>false</strong>.</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">scannerClass</td><td colspan="1" rowspan="1" class="confluenceTd">the name of the JAX-RS API scanner class, used to scope the application, resource packages, resource classes and classpath scanning, please refer to <a shape="rect" class="external-link" href="https:// github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#resource-scanning" rel="nofollow">Resource Scanning</a> section</td><td colspan="1" rowspan="1" class="confluenceTd">null</td><td colspan="1" rowspan="1" class="confluenceTd">io.swagger.v3.jaxrs2.integration.JaxrsApplicationScanner</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"> <pre class="brush: java; gutter: false; theme: Default">import org.apache.cxf.jaxrs.openapi.OpenApiFeature; import io.swagger.v3.oas.models.security.SecurityScheme; import io.swagger.v3.oas.models.security.SecurityScheme.Type; @@ -148,7 +148,7 @@ feature.setContactEmail("c...@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><h2 id="OpenApiFeature-ConfiguringfromSpring">Configuring from Spring</h2><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> +</div></div><p><br clear="none"></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"><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" @@ -181,7 +181,7 @@ feature.setSecurityDefinitions(Collectio </jaxrs:features> </jaxrs:server> </beans></pre> -</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"> +</div></div><p><br clear="none"></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">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"><blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0" @@ -218,7 +218,7 @@ feature.setSecurityDefinitions(Collectio </jaxrs:features> </jaxrs:server> </blueprint></pre> -</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"> +</div></div><p><br clear="none"></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"><web-app> <context-param> <param-name>contextParam</param-name> @@ -246,13 +246,13 @@ feature.setSecurityDefinitions(Collectio </servlet-mapping> </web-app></pre> -</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. By default, <strong>OpenApiFeature</strong> scans for known OpenAPI configuration locations and loads them if available (the behavior could be switched off by setting <strong>scanKnownConfigLocations</strong> to <strong>false</strong>). Please take into account that there is a certain level of the overlap between b oth.</p><p>Note that the properties, if available, do not override the properties which may have been set as suggested above from the code or Spring/Blueprint contexts or web.xml. Instead they complement and serve as the default configuration properties: for example, if some properties have been set from the code then the values for the same properties found in the properties file will not be used.</p><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 or/and <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/distribution/src/main/release/samples/jax_rs/spring_boot_scan/application/src/main/resources/application.yml#L13" rel="nofollow">sample s/jax_rs/spring_boot_scan</a> on how to auto-enable it. By default, the <strong>OpenApiCustomizer</strong> instance will be preconfigured for  <strong>OpenApiFeature</strong> since the base path is often unknown to CXF.</p><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"> +</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. By default, <strong>OpenApiFeature</strong> scans for known OpenAPI configuration locations and loads them if available (the behavior could be switched off by setting <strong>scanKnownConfigLocations</strong> to <strong>false</strong>). Please take into account that there is a certain level of the overlap between b oth.</p><p>Note that the properties, if available, do not override the properties which may have been set as suggested above from the code or Spring/Blueprint contexts or web.xml. Instead they complement and serve as the default configuration properties: for example, if some properties have been set from the code then the values for the same properties found in the properties file will not be used.</p><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 or/and <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/distribution/src/main/release/samples/jax_rs/spring_boot_scan/application/src/main/resources/application.yml#L13" rel="nofollow">sample s/jax_rs/spring_boot_scan</a> on how to auto-enable it. By default, the <strong>OpenApiCustomizer</strong> instance will be preconfigured for  <strong>OpenApiFeature</strong> since the base path is often unknown to CXF.</p><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><br clear="none"></p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> <pre class="brush: java; gutter: false; theme: Default"><dependency> <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-ConfiguringSwaggerUI(3.2.7+)">Configuring Swagger UI (3.2.7+)</h2><p>The <strong>OpenApiFeature</strong>  has a way to pre-configure certain  Swagger UI parameters (<a shape="rect" class="external-link" href="https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md" rel="nofollow">https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md</a>) through <strong><span class="blob-code-inner blob-code-marker-addition"><span class="pl-smi">SwaggerUiConfig</span></span></strong><span class="blob-code-inner blob-code-marker-addition">. The</span><strong><span class="blob-code-inner blob-code-marker-addition"> </span></strong>way it is implemented is by passing those parameters as a query string so the Swagger UI could adjust itself.</p><h2 id="OpenApiFeature-OpenApiFeature-UsingMultipleServerEndpoints(3.3.0+)UsingMultipleServe rEndpoints(3.3.0+)"><span class="confluence-anchor-link" id="OpenApiFeature-OpenApiFeature-UsingMultipleServerEndpoints(3.3.0+)"></span>Using Multiple Server Endpoints (3.3.0+)</h2><p>Quite often there are more than one <strong>JAXRSServerFactoryBean</strong> configured within same Apache CXF application, for example, under <strong>"/admin"</strong> and <strong>"/public"</strong> endpoints. The older <strong>Swagger/OpenAPI v2.0</strong> integrations used such <strong>basePath</strong> to disambiguate multiple API documentation contexts, but since <strong>OpenAPI v3.0 Specification</strong> does not explicitly include the concept of <strong>basePath</strong> anymore, this approach is not working. Luckily, starting from <strong>2.0.6</strong> release, Swagger OpenAPI v3 implementation properly supports <strong>Context Id</strong>. To activate it from <strong>OpenApiFeature</strong>, it is enough to set <strong>useContextBasedConfig </strong>property to <strong>true</strong> (very lik ely you would also want to set <strong>scan</strong> to <strong>false</strong>).</p><p><br clear="none"></p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> +</div></div><p><br clear="none"></p><p>For example, let's assume a JAX-RS endpoint is published at '<span><a shape="rect" class="external-link" href="http://hostport" rel="nofollow">http://host:port/context/services/</a></span>'.</p><p>Open the browser and go to '<span><a shape="rect" class="external-link" href="http://hostport" rel="nofollow">http://host:port/context/services/</a></span>api-docs/?url=/openapi.json' which will return a Swagger UI page.</p><p>CXF Services page will also link to Swagger UI. Go to '<span><a shape="rect" class="external-link" href="http://hostport" rel="nofollow">http://host:port/context/services/</a></span>' and follow a Swagger link which will return a Swagger UI page.</p><p>See <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_openapi_v3" rel="nofollow">samples/jax_rs/description_openapi_v3</a> as an example.</p><p>To deactivate automatic Swagger UI inte gration please set<strong> 'supportSwaggerUi'</strong> property to "<strong>false</strong>".</p><h2 id="OpenApiFeature-ConfiguringSwaggerUI(3.2.7+)">Configuring Swagger UI (3.2.7+)</h2><p>The <strong>OpenApiFeature</strong>  has a way to pre-configure certain  Swagger UI parameters (<a shape="rect" class="external-link" href="https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md" rel="nofollow">https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md</a>) through <strong><span class="blob-code-inner blob-code-marker-addition"><span class="pl-smi">SwaggerUiConfig</span></span></strong><span class="blob-code-inner blob-code-marker-addition">. The</span><strong><span class="blob-code-inner blob-code-marker-addition"> </span></strong>way it is implemented is by passing those parameters as a query string so the Swagger UI could adjust itself.</p><h2 id="OpenApiFeature-OpenApiFeature-UsingMultipleServerEndpoints(3.3.0+)UsingMu ltipleServerEndpoints(3.3.0+)"><span class="confluence-anchor-link" id="OpenApiFeature-OpenApiFeature-UsingMultipleServerEndpoints(3.3.0+)"></span>Using Multiple Server Endpoints (3.3.0+)</h2><p>Quite often there are more than one <strong>JAXRSServerFactoryBean</strong> configured within same Apache CXF application, for example, under <strong>"/admin"</strong> and <strong>"/public"</strong> endpoints. The older <strong>Swagger/OpenAPI v2.0</strong> integrations used such <strong>basePath</strong> to disambiguate multiple API documentation contexts, but since <strong>OpenAPI v3.0 Specification</strong> does not explicitly include the concept of <strong>basePath</strong> anymore, this approach is not working. Luckily, starting from <strong>2.0.6</strong> release, Swagger OpenAPI v3 implementation properly supports <strong>Context Id</strong>. To activate it from <strong>OpenApiFeature</strong>, it is enough to set <strong>useContextBasedConfig </strong>property to <strong>true</strong > (very likely you would also want to set <strong>scan</strong> to > <strong>false</strong>).</p><p><br clear="none"></p><div class="code panel > pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> <pre class="brush: java; gutter: false; theme: Default">final OpenApiFeature feature = new OpenApiFeature(); feature.setScan(false); feature.setUseContextBasedConfig(true);