| |
| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <!-- |
| |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <html> |
| <head> |
| |
| <link type="text/css" rel="stylesheet" href="/resources/site.css"> |
| <script src='/resources/space.js'></script> |
| |
| <meta http-equiv="Content-type" content="text/html;charset=UTF-8"> |
| <meta name="keywords" content="business integration, EAI, SOA, Service Oriented Architecture, web services, SOAP, JBI, JMS, WSDL, XML, EDI, Electronic Data Interchange, standards support, integration standards, application integration, middleware, software, solutions, services, CXF, open source"> |
| <meta name="description" content="Apache CXF, Services Framework - OpenApiFeature"> |
| |
| |
| <link type="text/css" rel="stylesheet" href="/resources/highlighter/styles/shCoreCXF.css"> |
| <link type="text/css" rel="stylesheet" href="/resources/highlighter/styles/shThemeCXF.css"> |
| |
| <script src='/resources/highlighter/scripts/shCore.js'></script> |
| <script src='/resources/highlighter/scripts/shBrushBash.js'></script> |
| <script src='/resources/highlighter/scripts/shBrushXml.js'></script> |
| <script src='/resources/highlighter/scripts/shBrushJava.js'></script> |
| <script> |
| SyntaxHighlighter.defaults['toolbar'] = false; |
| SyntaxHighlighter.all(); |
| </script> |
| |
| |
| <title> |
| Apache CXF -- OpenApiFeature |
| </title> |
| </head> |
| <body onload="init()"> |
| |
| |
| <table width="100%" cellpadding="0" cellspacing="0"> |
| <tr> |
| <td id="cell-0-0" colspan="2"> </td> |
| <td id="cell-0-1"> </td> |
| <td id="cell-0-2" colspan="2"> </td> |
| </tr> |
| <tr> |
| <td id="cell-1-0"> </td> |
| <td id="cell-1-1"> </td> |
| <td id="cell-1-2"> |
| <!-- Banner --> |
| <div class="banner" id="banner"><div><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr><td align="left" colspan="1" nowrap> |
| <a shape="rect" href="http://cxf.apache.org/" title="Apache CXF"><span style="font-weight: bold; font-size: 170%; color: white">Apache CXF</span></a> |
| </td><td align="right" colspan="1" nowrap> |
| <a shape="rect" href="http://www.apache.org/" title="The Apache Sofware Foundation"><img border="0" alt="ASF Logo" src="http://cxf.apache.org/images/asf-logo.png"></a> |
| </td></tr></table></div></div> |
| <!-- Banner --> |
| <div id="top-menu"> |
| <table border="0" cellpadding="1" cellspacing="0" width="100%"> |
| <tr> |
| <td> |
| <div align="left"> |
| <!-- Breadcrumbs --> |
| <a href="index.html">Index</a> > <a href="configuration.html">Configuration</a> > <a href="featureslist.html">FeaturesList</a> > <a href="openapifeature.html">OpenApiFeature</a> |
| <!-- Breadcrumbs --> |
| </div> |
| </td> |
| <td> |
| <div align="right"> |
| <!-- Quicklinks --> |
| <div id="quicklinks"><p><a shape="rect" href="http://cxf.apache.org/download.html">Download</a> | <a shape="rect" href="http://cxf.apache.org/docs/index.html">Documentation</a></p></div> |
| <!-- Quicklinks --> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </td> |
| <td id="cell-1-3"> </td> |
| <td id="cell-1-4"> </td> |
| </tr> |
| <tr> |
| <td id="cell-2-0" colspan="2"> </td> |
| <td id="cell-2-1"> |
| <table> |
| <tr valign="top"> |
| <td height="100%"> |
| <div id="wrapper-menu-page-right"> |
| <div id="wrapper-menu-page-top"> |
| <div id="wrapper-menu-page-bottom"> |
| <div id="menu-page"> |
| <!-- NavigationBar --> |
| <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><form enctype="application/x-www-form-urlencoded" method="get" id="cse-search-box" action="http://www.google.com/cse"> |
| <div> |
| <input type="hidden" name="cx" value="002890367768291051730:o99qiwa09y4"> |
| <input type="hidden" name="ie" value="UTF-8"> |
| <input type="text" name="q" size="21"> |
| <input type="submit" name="sa" value="Search"> |
| </div> |
| </form> |
| <script type="text/javascript" src="http://www.google.com/cse/brand?form=cse-search-box&lang=en"></script><hr><ul class="alternate"><li><a shape="rect" href="http://cxf.apache.org/javadoc/latest/">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> </p><p><a shape="rect" class="external-link" href="http://www.apache.org/events/current-event.html"><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image confluence-external-resource" src="http://www.apache.org/events/current-event-125x125.png" data-image-src="http://www.apache.org/events/current-event-125x125.png"></span></a></p></div> |
| <!-- NavigationBar --> |
| </div> |
| </div> |
| </div> |
| </div> |
| </td> |
| <td height="100%"> |
| <!-- Content --> |
| <div class="wiki-content"> |
| <div id="ConfluenceContent"><p><style type="text/css">/*<![CDATA[*/ |
| div.rbtoc1636141722850 {padding: 0px;} |
| div.rbtoc1636141722850 ul {list-style: disc;margin-left: 0px;} |
| div.rbtoc1636141722850 li {margin-left: 0px;padding-left: 0px;} |
| |
| /*]]>*/</style></p><div class="toc-macro rbtoc1636141722850"> |
| <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> |
| </div><h1 id="OpenApiFeature-Introduction">Introduction</h1><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><h1 id="OpenApiFeature-Setup">Setup</h1><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.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, 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><h1 id="OpenApiFeature-Properties">Properties</h1><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="wrapped confluenceTable"><colgroup span="1"><col span="1" style="width: 236.0px;"><col span="1" style="width: 511.0px;"><col span="1" style="width: 203.0px;"><col span="1" style="width: 372.0px;"></colgroup><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh">Name</th><th colspan="1" rowspan="1" class="confluenceTh">Description</th><th colspan="1" rowspan="1" class="confluenceTh">Default 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">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">/config/openapi-configuration.yml</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">scanKnownConfigLocations</td><td colspan="1" rowspan="1" class="confluenceTd"><p>scan known OpenAPI configuration location (classpath or filesystem), which are:</p><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent"> |
| <pre>openapi-configuration.yaml |
| 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="confluenceTd">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="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" 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><h1 id="OpenApiFeature-ConfiguringfromCode">Configuring from Code</h1><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; |
| |
| ... |
| |
| final OpenApiFeature feature = new OpenApiFeature(); |
| 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><br clear="none"></p><h1 id="OpenApiFeature-ConfiguringfromSpring">Configuring from Spring</h1><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" |
| xsi:schemaLocation="http://cxf.apache.org/core http://cxf.apache.org/schemas/core.xsd |
| http://cxf.apache.org/jaxrs http://cxf.apache.org/schemas/jaxrs.xsd |
| http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd"> |
| ... |
| <!-- JAXRS providers --> |
| <bean id="jsonProvider" class="com.fasterxml.jackson.jaxrs.json.JacksonJsonProvider" /> |
| |
| <!-- Application resources --> |
| <bean id="sampleResource" class="demo.jaxrs.openapi.server.Sample" /> |
| |
| <!-- CXF OpenApiFeature --> |
| <bean id="openApiFeature" class="org.apache.cxf.jaxrs.openapi.OpenApiFeature"> |
| <!-- customize some of the properties --> |
| </bean> |
| |
| ... |
| |
| <jaxrs:server id="sampleServer" address="/swaggerSample"> |
| <jaxrs:serviceBeans> |
| <ref bean="sampleResource" /> |
| </jaxrs:serviceBeans> |
| <jaxrs:providers> |
| <ref bean="jsonProvider" /> |
| </jaxrs:providers> |
| <jaxrs:features> |
| <ref bean="openApiFeature" /> |
| </jaxrs:features> |
| </jaxrs:server> |
| </beans></pre> |
| </div></div><p><br clear="none"></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"> |
| <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" |
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xmlns:cxf="http://cxf.apache.org/blueprint/core" |
| xmlns:jaxrs="http://cxf.apache.org/blueprint/jaxrs" |
| xsi:schemaLocation="http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd |
| http://cxf.apache.org/blueprint/core http://cxf.apache.org/schemas/blueprint/core.xsd |
| http://cxf.apache.org/jaxrs http://cxf.apache.org/schemas/blueprint/jaxrs.xsd"> |
| ... |
| <!-- JAXRS providers --> |
| <bean id="jsonProvider" class="com.fasterxml.jackson.jaxrs.json.JacksonJsonProvider" /> |
| |
| <!-- Application resources --> |
| <bean id="sampleResource" class="demo.jaxrs.openapi.server.Sample" /> |
| |
| |
| <!-- CXF OpenApiFeature --> |
| <bean id="openApiFeature" class="org.apache.cxf.jaxrs.openapi.OpenApiFeature"> |
| <!-- customize some of the properties --> |
| </bean> |
| |
| ... |
| |
| <jaxrs:server id="sampleServer" address="/swaggerSample"> |
| <jaxrs:serviceBeans> |
| <ref component-id="sampleResource" /> |
| </jaxrs:serviceBeans> |
| <jaxrs:providers> |
| <ref component-id="jsonProvider" /> |
| </jaxrs:providers> |
| <jaxrs:features> |
| <ref component-id="openApiFeature" /> |
| </jaxrs:features> |
| </jaxrs:server> |
| </blueprint></pre> |
| </div></div><p><br clear="none"></p><h1 id="OpenApiFeature-ConfiguringinCXFNonSpringJaxrsServlet">Configuring in CXFNonSpringJaxrsServlet</h1><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> |
| <param-value>contextParamValue</param-value> |
| </context-param> |
| |
| <servlet> |
| <servlet-name>CXFServlet</servlet-name> |
| <display-name>CXF Servlet</display-name> |
| <servlet-class>org.apache.cxf.jaxrs.servlet.CXFNonSpringJaxrsServlet</servlet-class> |
| <init-param> |
| <param-name>jaxrs.serviceClasses</param-name> |
| <param-value>org.apache.cxf.systest.jaxrs.BookStore</param-value> |
| </init-param> |
| <init-param> |
| <param-name>jaxrs.features</param-name> |
| <param-value>org.apache.cxf.jaxrs.openapi.OpenApiFeature</param-value> |
| </init-param> |
| <load-on-startup>1</load-on-startup> |
| </servlet> |
| |
| <servlet-mapping> |
| <servlet-name>CXFServlet</servlet-name> |
| <url-pattern>/*</url-pattern> |
| </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 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 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">samples/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: java; gutter: false; theme: Default"><dependency> |
| <groupId>org.webjars</groupId> |
| <artifactId>swagger-ui</artifactId> |
| <version>3.13.0</version> |
| </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 integration 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><h1 id="OpenApiFeature-OpenApiFeature-UsingMultipleServerEndpoints(3.3.0+)UsingMultipleServerEndpoints(3.3.0+)"><span class="confluence-anchor-link" id="OpenApiFeature-OpenApiFeature-UsingMultipleServerEndpoints(3.3.0+)"></span>Using Multiple Server Endpoints (3.3.0+)</h1><p>Quite often there are more than one <strong>JAXRSServerFactoryBean</strong> configured within same Apache CXF application, for example, under <strong>"/admin"</strong> and <strong>"/public"</strong> endpoints. The older <strong>Swagger/OpenAPI v2.0</strong> integrations used such <strong>basePath</strong> to disambiguate multiple API documentation contexts, but since <strong>OpenAPI v3.0 Specification</strong> does not explicitly include the concept of <strong>basePath</strong> anymore, this approach is not working. Luckily, starting from <strong>2.0.6</strong> release, Swagger OpenAPI v3 implementation properly supports <strong>Context Id</strong>. To activate it from <strong>OpenApiFeature</strong>, it is enough to set <strong>useContextBasedConfig </strong>property to <strong>true</strong> (very likely you would also want to set <strong>scan</strong> to <strong>false</strong>).</p><p><br clear="none"></p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> |
| <pre class="brush: java; gutter: false; theme: Default">final OpenApiFeature feature = new OpenApiFeature(); |
| feature.setScan(false); |
| feature.setUseContextBasedConfig(true); |
| ...</pre> |
| </div></div><p>With that, each <strong>OpenApiFeature</strong> will generate unique <strong>Context Id</strong> and won't see any classes / packages beyond its own configuration.</p><h1 id="OpenApiFeature-Samples">Samples</h1><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><li><a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_openapi_v3_web" rel="nofollow">samples/jax_rs/description_openapi_v3_web</a><span>: 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> sample using OpenApiFeature inside WAR-based deployment</span></li><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_spring" rel="nofollow">samples/jax_rs/description_openapi_v3_spring</a>:</span> <span>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> sample using Spring and multiple context paths / OpenApiFeatures</span><br clear="none"><span><br clear="none"></span></li></ul></div></div> |
| </div> |
| <!-- Content --> |
| </td> |
| </tr> |
| </table> |
| </td> |
| <td id="cell-2-2" colspan="2"> </td> |
| </tr> |
| <tr> |
| <td id="cell-3-0"> </td> |
| <td id="cell-3-1"> </td> |
| <td id="cell-3-2"> |
| <div id="footer"> |
| <!-- Footer --> |
| <div id="site-footer"> |
| <a href="http://cxf.apache.org/privacy-policy.html">Privacy Policy</a> - |
| (<a href="https://cwiki.apache.org/confluence/pages/editpage.action?pageId=75979822">edit page</a>) |
| (<a href="https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=75979822&showComments=true&showCommentArea=true#addcomment">add comment</a>)<br> |
| Apache CXF, CXF, Apache, the Apache feather logo are trademarks of The Apache Software Foundation.<br> |
| All other marks mentioned may be trademarks or registered trademarks of their respective owners. |
| </div> |
| <!-- Footer --> |
| </div> |
| </td> |
| <td id="cell-3-3"> </td> |
| <td id="cell-3-4"> </td> |
| </tr> |
| <tr> |
| <td id="cell-4-0" colspan="2"> </td> |
| <td id="cell-4-1"> </td> |
| <td id="cell-4-2" colspan="2"> </td> |
| </tr> |
| </table> |
| |
| <script type="text/javascript"> |
| var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); |
| document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); |
| </script> |
| <script type="text/javascript"> |
| try { |
| var pageTracker = _gat._getTracker("UA-4458903-1"); |
| pageTracker._trackPageview(); |
| } catch(err) {}</script> |
| |
| </body> |
| </html> |
| |
