Author: buildbot Date: Sun Aug 28 13:42:51 2022 New Revision: 1080610 Log: Production update by buildbot for cxf
Modified: websites/production/cxf/content/cache/docs.pageCache websites/production/cxf/content/docs/openapifeature.html Modified: websites/production/cxf/content/cache/docs.pageCache ============================================================================== Binary files - no diff available. Modified: websites/production/cxf/content/docs/openapifeature.html ============================================================================== --- websites/production/cxf/content/docs/openapifeature.html (original) +++ websites/production/cxf/content/docs/openapifeature.html Sun Aug 28 13:42:51 2022 @@ -59,7 +59,7 @@ Apache CXF -- OpenApiFeature <td id="cell-1-1"> </td> <td id="cell-1-2"> <!-- Banner --> -<div class="banner" id="banner"><div class="table-wrap"><table class="confluenceTable" style="width: 100.0%;" border="0" cellpadding="0" cellspacing="0"><colgroup span="1"><col span="1"><col span="1"></colgroup><tbody><tr><td align="left" colspan="1" rowspan="1" class="confluenceTd" style="border: none;"><a shape="rect" href="http://cxf.apache.org/" title="Apache CXF"> <span style="color: white;font-size: 170.0%;font-weight: bold;">Apache CXF</span> </a></td><td align="right" colspan="1" rowspan="1" class="confluenceTd" style="border: none;"><a shape="rect" class="external-link" href="http://www.apache.org/" title="The Apache Software Foundation"> <span class="confluence-embedded-file-wrapper image-right-wrapper confluence-embedded-manual-size"><img class="confluence-embedded-image confluence-external-resource image-right" alt="The Apache Software Foundation" width="214" src="https://apache.org/img/asf_logo.png" data-image-src="https://apache.org/img/asf_logo.png"></span> </a></td>< /tr></tbody></table></div></div> +<div class="banner" id="banner"><div class="table-wrap"><table class="confluenceTable" style="width: 100.0%;" border="0" cellpadding="0" cellspacing="0"><colgroup span="1"><col span="1"><col span="1"></colgroup><tbody><tr><td align="left" colspan="1" rowspan="1" class="confluenceTd" style="border: none;"><a shape="rect" href="http://cxf.apache.org/" title="Apache CXF"> <span style="color: white;font-size: 170.0%;font-weight: bold;">Apache CXF</span> </a></td><td align="right" colspan="1" rowspan="1" class="confluenceTd" style="border: none;"><a shape="rect" class="external-link" href="http://www.apache.org/" title="The Apache Software Foundation"> <span class="confluence-embedded-file-wrapper image-right-wrapper confluence-embedded-manual-size"><img class="confluence-embedded-image confluence-external-resource image-right" draggable="false" alt="The Apache Software Foundation" width="214" src="https://apache.org/img/asf_logo.png" data-image-src="https://apache.org/img/asf_logo.png"> </span> </a></td></tr></tbody></table></div></div> <!-- Banner --> <div id="top-menu"> <table border="0" cellpadding="1" cellspacing="0" width="100%"> @@ -99,7 +99,7 @@ Apache CXF -- OpenApiFeature <div id="navigation"><ul class="alternate"><li><a shape="rect" href="overview.html">Overview</a></li><li><a shape="rect" href="how-tos.html">How-Tos</a></li><li><a shape="rect" href="frontends.html">Frontends</a></li><li><a shape="rect" href="databindings.html">DataBindings</a></li><li><a shape="rect" href="transports.html">Transports</a></li><li><a shape="rect" href="configuration.html">Configuration</a></li><li><a shape="rect" href="debugging-and-logging.html">Debugging and Logging</a></li><li><a shape="rect" href="tools.html">Tools</a></li><li><a shape="rect" href="restful-services.html">RESTful Services</a></li><li><a shape="rect" href="wsdl-bindings.html">WSDL Bindings</a></li><li><a shape="rect" href="service-routing.html">Service Routing</a></li><li><a shape="rect" href="dynamic-languages.html">Dynamic Languages</a></li><li><a shape="rect" href="ws-support.html">WS-* Support</a></li><li><a shape="rect" href="advanced-integration.html">Advanced Integration</a></li><li><a shape ="rect" href="deployment.html">Deployment</a></li><li><a shape="rect" href="schemas-and-namespaces.html">Use of Schemas and Namespaces</a></li></ul><hr><ul class="alternate"><li><p>Search</p></li></ul><iframe frameborder="1" scrolling="auto" id="searchId" src="https://cxf.apache.org/resources/search.htm" name="SearchIFrame" width="200px" style="border:none;" title="Search" height="60px"><p><br clear="none"></p></iframe> -<hr><ul class="alternate"><li><a shape="rect" href="http://cxf.apache.org/javadoc/latest-3.5.x/">API 3.5.x (Javadoc)</a></li><li><a shape="rect" href="http://cxf.apache.org/javadoc/latest-3.2.x/">API 3.2.x (Javadoc)</a></li><li><a shape="rect" href="http://cxf.apache.org/javadoc/latest-3.1.x/">API 3.1.x (Javadoc)</a></li><li><a shape="rect" href="http://cxf.apache.org/">CXF Website</a></li></ul><p><br clear="none"></p><p><a shape="rect" class="external-link" href="https://www.apache.org/events/current-event.html"> <span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image confluence-external-resource" src="https://www.apache.org/events/current-event-125x125.png" data-image-src="https://www.apache.org/events/current-event-125x125.png"></span> </a></p></div> +<hr><ul class="alternate"><li><a shape="rect" href="http://cxf.apache.org/javadoc/latest-3.5.x/">API 3.5.x (Javadoc)</a></li><li><a shape="rect" href="http://cxf.apache.org/javadoc/latest-3.2.x/">API 3.2.x (Javadoc)</a></li><li><a shape="rect" href="http://cxf.apache.org/javadoc/latest-3.1.x/">API 3.1.x (Javadoc)</a></li><li><a shape="rect" href="http://cxf.apache.org/">CXF Website</a></li></ul><p><br clear="none"></p><p><a shape="rect" class="external-link" href="https://www.apache.org/events/current-event.html"> <span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image confluence-external-resource" draggable="false" src="https://www.apache.org/events/current-event-125x125.png" data-image-src="https://www.apache.org/events/current-event-125x125.png"></span> </a></p></div> <!-- NavigationBar --> </div> </div> @@ -110,11 +110,11 @@ Apache CXF -- OpenApiFeature <!-- Content --> <div class="wiki-content"> <div id="ConfluenceContent"><p><style type="text/css">/*<![CDATA[*/ -div.rbtoc1654040571314 {padding: 0px;} -div.rbtoc1654040571314 ul {list-style: disc;margin-left: 0px;} -div.rbtoc1654040571314 li {margin-left: 0px;padding-left: 0px;} +div.rbtoc1661694167482 {padding: 0px;} +div.rbtoc1661694167482 ul {list-style: disc;margin-left: 0px;} +div.rbtoc1661694167482 li {margin-left: 0px;padding-left: 0px;} -/*]]>*/</style></p><div class="toc-macro rbtoc1654040571314"> +/*]]>*/</style></p><div class="toc-macro rbtoc1661694167482"> <ul class="toc-indentation"><li><a shape="rect" href="#OpenApiFeature-Introduction">Introduction</a></li><li><a shape="rect" href="#OpenApiFeature-Setup">Setup</a></li><li><a shape="rect" href="#OpenApiFeature-Properties">Properties</a></li><li><a shape="rect" href="#OpenApiFeature-ConfiguringfromCode">Configuring from Code</a></li><li><a shape="rect" href="#OpenApiFeature-ConfiguringfromSpring">Configuring from Spring</a></li><li><a shape="rect" href="#OpenApiFeature-ConfiguringinBlueprint">Configuring in Blueprint</a></li><li><a shape="rect" href="#OpenApiFeature-ConfiguringinCXFNonSpringJaxrsServlet">Configuring in CXFNonSpringJaxrsServlet</a></li><li><a shape="rect" href="#OpenApiFeature-ConfiguringfromPropertyfiles">Configuring from Property files</a></li><li><a shape="rect" href="#OpenApiFeature-SpringBootAutoConfiguration">Spring Boot Auto Configuration</a></li><li><a shape="rect" href="#OpenApiFeature-EnablingSwaggerUI">Enabling Swagger UI</a> <ul class="toc-indentation"><li><a shape="rect" href="#OpenApiFeature-EnablingSwaggerUIinOSGicontainer(Karaf)">Enabling Swagger UI in OSGi container (Karaf)</a></li><li><a shape="rect" href="#OpenApiFeature-ConfiguringSwaggerUI(3.2.7+)">Configuring Swagger UI (3.2.7+)</a></li></ul> </li><li><a shape="rect" href="#OpenApiFeature-OpenApiFeature-UsingMultipleServerEndpoints(3.3.0+)UsingMultipleServerEndpoints(3.3.0+)">Using Multiple Server Endpoints (3.3.0+)</a></li><li><a shape="rect" href="#OpenApiFeature-Samples">Samples</a></li></ul> @@ -239,7 +239,7 @@ feature.setSecurityDefinitions(Collectio </servlet-mapping> </web-app></pre> -</div></div><h1 id="OpenApiFeature-ConfiguringfromPropertyfiles">Configuring from Property files</h1><p>It is possible to supply the configuration from the property files. The default location for a properties file is "<strong>/swagger.properties</strong>". <strong>OpenApiFeature</strong> will pick it up if it is available, and the location can be overridden with a<strong> 'propertiesLocation</strong>' property.  Additionally, the complete OpenAPI configuration could be supplied from the property file (usually <strong>openapi-configuration.json</strong> or <strong>openapi-configuration.yml</strong>), controlled by '<strong>configLocation'</strong> property. By default, <strong>OpenApiFeature</strong> scans for known OpenAPI configuration locations and loads them if available (the behavior could be switched off by setting <strong>scanKnownConfigLocations</strong> to <strong>false</strong>). Please take into account that there is a certain level of the overlap between b oth.</p><p>Note that the properties, if available, do not override the properties which may have been set as suggested above from the code or Spring/Blueprint contexts or web.xml. Instead they complement and serve as the default configuration properties: for example, if some properties have been set from the code then the values for the same properties found in the properties file will not be used.</p><h1 id="OpenApiFeature-SpringBootAutoConfiguration">Spring Boot Auto Configuration</h1><p>Please consult <a shape="rect" class="external-link" rel="nofollow" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/spring_boot">samples/jax_rs/spring_boot</a> and on how to create <strong>OpenApiFeature</strong> as a @Bean or/and <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/distribution/src/main/release/samples/jax_rs/spring_boot_scan/application/src/main/resources/application.yml#L13" rel="nofollow">sample s/jax_rs/spring_boot_scan</a> on how to auto-enable it. By default, the <strong>OpenApiCustomizer</strong> instance will be preconfigured for  <strong>OpenApiFeature</strong> since the base path is often unknown to CXF.</p><h1 id="OpenApiFeature-EnablingSwaggerUI">Enabling Swagger UI</h1><p>Adding a Swagger UI Maven dependency is all what is needed to start accessing Swagger documents with the help of Swagger UI.</p><div class="syntaxhighlighter nogutter xml"><p><br clear="none"></p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> +</div></div><h1 id="OpenApiFeature-ConfiguringfromPropertyfiles">Configuring from Property files</h1><p>It is possible to supply the configuration from the property files. The default location for a properties file is "<strong>/swagger.properties</strong>". <strong>OpenApiFeature</strong> will pick it up if it is available, and the location can be overridden with a<strong> 'propertiesLocation</strong>' property.  Additionally, the complete OpenAPI configuration could be supplied from the property file (usually <strong>openapi-configuration.json</strong> or <strong>openapi-configuration.yml</strong>), controlled by '<strong>configLocation'</strong> property. By default, <strong>OpenApiFeature</strong> scans for known OpenAPI configuration locations and loads them if available (the behavior could be switched off by setting <strong>scanKnownConfigLocations</strong> to <strong>false</strong>). Please take into account that there is a certain level of the overlap between b oth.</p><p>Note that the properties, if available, do not override the properties which may have been set as suggested above from the code or Spring/Blueprint contexts or web.xml. Instead they complement and serve as the default configuration properties: for example, if some properties have been set from the code then the values for the same properties found in the properties file will not be used.</p><h1 id="OpenApiFeature-SpringBootAutoConfiguration">Spring Boot Auto Configuration</h1><p>Please consult <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/spring_boot" rel="nofollow">samples/jax_rs/spring_boot</a> and on how to create <strong>OpenApiFeature</strong> as a @Bean or/and <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/distribution/src/main/release/samples/jax_rs/spring_boot_scan/application/src/main/resources/application.yml#L13" rel="nofollow">sample s/jax_rs/spring_boot_scan</a> on how to auto-enable it. By default, the <strong>OpenApiCustomizer</strong> instance will be preconfigured for  <strong>OpenApiFeature</strong> since the base path is often unknown to CXF.</p><h1 id="OpenApiFeature-EnablingSwaggerUI">Enabling Swagger UI</h1><p>Adding a Swagger UI Maven dependency is all what is needed to start accessing Swagger documents with the help of Swagger UI.</p><div class="syntaxhighlighter nogutter xml"><p><br clear="none"></p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> <pre class="brush: xml; gutter: false; theme: Default"><dependency> <groupId>org.webjars</groupId> <artifactId>swagger-ui</artifactId> @@ -247,7 +247,7 @@ feature.setSecurityDefinitions(Collectio </dependency></pre> </div></div><p><br clear="none"></p><p>For example, let's assume a JAX-RS endpoint is published at '<span><a shape="rect" class="external-link" href="http://hostport" rel="nofollow">http://host:port/context/services/</a></span>'.</p><p>Open the browser and go to '<span><a shape="rect" class="external-link" href="http://hostport" rel="nofollow">http://host:port/context/services/</a></span>api-docs/?url=/openapi.json' which will return a Swagger UI page.</p><p>CXF Services page will also link to Swagger UI. Go to '<span><a shape="rect" class="external-link" href="http://hostport" rel="nofollow">http://host:port/context/services/</a></span>' and follow a Swagger link which will return a Swagger UI page.</p><p>See <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_openapi_v3" rel="nofollow">samples/jax_rs/description_openapi_v3</a> as an example.</p><p>To deactivate automatic Swagger UI inte gration please set<strong> 'supportSwaggerUi'</strong> property to "<strong>false</strong>".</p><h2 id="OpenApiFeature-EnablingSwaggerUIinOSGicontainer(Karaf)">Enabling Swagger UI in OSGi container (Karaf)</h2><p>Since <strong>org.webjars</strong>/<strong>swagger-ui</strong> is just a package with resources, it won't be referenced in OSGi manifest as the required imports. Therefore, to make use of Swagger UI in the OSGi deployments, the <strong>org.webjars</strong>/<strong>swagger-ui</strong> should be installed manually, for example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> <pre class="brush: java; gutter: false; theme: Default">karaf@root()> install mvn:org.webjars/swagger-ui/3.23.8</pre> -</div></div><p>The dedicated Activator will take care of discovering the presence of the <strong>org.webjars</strong>/<strong>swagger-ui</strong> bundle and configuring <strong>OpenApiFeature</strong>.</p><h2 id="OpenApiFeature-ConfiguringSwaggerUI(3.2.7+)">Configuring Swagger UI (3.2.7+)</h2><p>The <strong>OpenApiFeature</strong>  has a way to pre-configure certain  Swagger UI parameters (<a shape="rect" class="external-link" href="https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md" rel="nofollow">https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md</a>) through <strong><span class="blob-code-inner blob-code-marker-addition"><span class="pl-smi">SwaggerUiConfig</span></span></strong><span class="blob-code-inner blob-code-marker-addition">. The</span><strong><span class="blob-code-inner blob-code-marker-addition"> </span></strong>way it is implemented is by passing those parameters as a query string so the Swagger UI could adjust itself.</p></div><p><br clear="none"></p><div class="confluence-information-macro confluence-information-macro-warning"><span class="aui-icon aui-icon-small aui-iconfont-error confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>Apache CXF prior to 3.4.6 / 3.5.1 passed Swagger UI configuration (url, ...) as query parameters. Starting from Swagger UI <strong>4.1.3</strong>, most of query parameters are not accepted anymore (due to security concerns), and Apache CXF employes different strategy and tries to replace the URL dynamically (inside HTML) when serving Swagger UI's front web page. This behaviour could be <strong>turned on </strong>by setting <code>queryConfigEnabled</code>  property of the <strong><span class="blob-code-inner blob-code-marker-addition"><span class="pl-smi">SwaggerUiConfig </span></span></strong><span class="blob-code-inner blob-code-marker-addition"><span class="pl-smi">to <code>true</code> (the defa ult value is <code>false</code> ).</span></span></p></div></div><p><br clear="none"></p><div class="syntaxhighlighter nogutter xml"><h1 id="OpenApiFeature-OpenApiFeature-UsingMultipleServerEndpoints(3.3.0+)UsingMultipleServerEndpoints(3.3.0+)"><span class="confluence-anchor-link" id="OpenApiFeature-OpenApiFeature-UsingMultipleServerEndpoints(3.3.0+)"></span>Using Multiple Server Endpoints (3.3.0+)</h1><p>Quite often there are more than one <strong>JAXRSServerFactoryBean</strong> configured within same Apache CXF application, for 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"> +</div></div><p>The dedicated Activator will take care of discovering the presence of the <strong>org.webjars</strong>/<strong>swagger-ui</strong> bundle and configuring <strong>OpenApiFeature</strong>.</p><h2 id="OpenApiFeature-ConfiguringSwaggerUI(3.2.7+)">Configuring Swagger UI (3.2.7+)</h2><p>The <strong>OpenApiFeature</strong>  has a way to pre-configure certain  Swagger UI parameters (<a shape="rect" class="external-link" href="https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md" rel="nofollow">https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md</a>) through <strong><span class="blob-code-inner blob-code-marker-addition"><span class="pl-smi">SwaggerUiConfig</span></span></strong><span class="blob-code-inner blob-code-marker-addition">. The</span><strong><span class="blob-code-inner blob-code-marker-addition"> </span></strong>way it is implemented is by passing those parameters as a query string so the Swagger UI could adjust itself.</p></div><p><br clear="none"></p><div class="confluence-information-macro confluence-information-macro-warning"><span class="aui-icon aui-icon-small aui-iconfont-error confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>Apache CXF prior to 3.4.6 / 3.5.1 passed Swagger UI configuration (url, ...) as query parameters. Starting from Swagger UI <strong>4.1.3</strong>, most of query parameters are not accepted anymore (due to security concerns), and Apache CXF employes different strategy and tries to replace the URL dynamically (inside HTML) when serving Swagger UI's front web page. This behaviour could be <strong>turned off </strong>by setting <code>queryConfigEnabled</code>  property of the <strong><span class="blob-code-inner blob-code-marker-addition"><span class="pl-smi">SwaggerUiConfig </span></span></strong><span class="blob-code-inner blob-code-marker-addition"><span class="pl-smi">to <code>true</code> (the def ault value is <code>false</code> and URLs are replaced dynamically). Please notice that in this case the customized Swagger UI bundle is required since <code>queryConfigEnabled</code>  property could only be set by altering the distribution (<a shape="rect" class="external-link" href="https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md" rel="nofollow">https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md</a>)<br clear="none"></span></span></p></div></div><p><br clear="none"></p><div class="syntaxhighlighter nogutter xml"><h1 id="OpenApiFeature-OpenApiFeature-UsingMultipleServerEndpoints(3.3.0+)UsingMultipleServerEndpoints(3.3.0+)"><span class="confluence-anchor-link" id="OpenApiFeature-OpenApiFeature-UsingMultipleServerEndpoints(3.3.0+)"></span>Using Multiple Server Endpoints (3.3.0+)</h1><p>Quite often there are more than one <strong>JAXRSServerFactoryBean</strong> configured within same Apache CXF application, for exam ple, under <strong>"/admin"</strong> and <strong>"/public"</strong> endpoints. The older <strong>Swagger/OpenAPI v2.0</strong> integrations used such <strong>basePath</strong> to disambiguate multiple API documentation contexts, but since <strong>OpenAPI v3.0 Specification</strong> does not explicitly include the concept of <strong>basePath</strong> anymore, this approach is not working. Luckily, starting from <strong>2.0.6</strong> release, Swagger OpenAPI v3 implementation properly supports <strong>Context Id</strong>. To activate it from <strong>OpenApiFeature</strong>, it is enough to set <strong>useContextBasedConfig </strong>property to <strong>true</strong> (very likely you would also want to set <strong>scan</strong> to <strong>false</strong>).</p><p><br clear="none"></p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> <pre class="brush: java; gutter: false; theme: Default">final OpenApiFeature feature = new OpenApiFeature(); feature.setScan(false); feature.setUseContextBasedConfig(true);