| |
| <!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 - Swagger2Feature"> |
| |
| |
| <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 -- Swagger2Feature |
| </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="swagger2feature.html">Swagger2Feature</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"><h1 id="Swagger2Feature-Swagger2Feature">Swagger2Feature</h1><p><style type="text/css">/*<![CDATA[*/ |
| div.rbtoc1636141549238 {padding: 0px;} |
| div.rbtoc1636141549238 ul {list-style: disc;margin-left: 0px;} |
| div.rbtoc1636141549238 li {margin-left: 0px;padding-left: 0px;} |
| |
| /*]]>*/</style></p><div class="toc-macro rbtoc1636141549238"> |
| <ul class="toc-indentation"><li><a shape="rect" href="#Swagger2Feature-Swagger2Feature">Swagger2Feature</a></li><li><a shape="rect" href="#Swagger2Feature-Setup">Setup</a></li><li><a shape="rect" href="#Swagger2Feature-Properties">Properties</a></li><li><a shape="rect" href="#Swagger2Feature-ConfiguringfromCode">Configuring from Code</a></li><li><a shape="rect" href="#Swagger2Feature-ConfiguringinSpring">Configuring in Spring</a></li><li><a shape="rect" href="#Swagger2Feature-ConfiguringinBlueprint">Configuring in Blueprint</a></li><li><a shape="rect" href="#Swagger2Feature-ConfiguringinCXFNonSpringJaxrsServlet">Configuring in CXFNonSpringJaxrsServlet</a></li><li><a shape="rect" href="#Swagger2Feature-New:ConfiguringfromPropertiesfile">New: Configuring from Properties file</a></li><li><a shape="rect" href="#Swagger2Feature-EnablinginSpringBoot">Enabling in Spring Boot</a></li><li><a shape="rect" href="#Swagger2Feature-AccessingSwaggerDocuments">Accessing Swagger Documents</a></li><li><a shape="rect" href="#Swagger2Feature-EnablingSwaggerUI">Enabling Swagger UI</a> |
| <ul class="toc-indentation"><li><a shape="rect" href="#Swagger2Feature-EnablingSwaggerUIinOSGicontainer(Karaf)">Enabling Swagger UI in OSGi container (Karaf)</a></li><li><a shape="rect" href="#Swagger2Feature-AutomaticUIActivation">Automatic UI Activation</a></li><li><a shape="rect" href="#Swagger2Feature-UnpackingSwaggerUIresources">Unpacking Swagger UI resources</a></li><li><a shape="rect" href="#Swagger2Feature-ConfiguringSwaggerUI(3.2.7+)">Configuring Swagger UI (3.2.7+)</a></li></ul> |
| </li><li><a shape="rect" href="#Swagger2Feature-ReverseProxy">Reverse Proxy</a></li><li><a shape="rect" href="#Swagger2Feature-ConvertingtoOpenAPIJSON">Converting to OpenAPI JSON</a></li><li><a shape="rect" href="#Swagger2Feature-Samples">Samples</a></li></ul> |
| </div><p><br clear="none"></p><p>The CXF Swagger2Feature allows you to generate <a shape="rect" class="external-link" href="http://swagger.io/specification/" rel="nofollow">Swagger 2.0</a> documents from JAX-RS service endpoints with a simple configuration.</p><p>For generating <a shape="rect" class="external-link" href="https://github.com/swagger-api/swagger-spec/blob/master/versions/1.2.md" rel="nofollow">Swagger 1.2</a> documents, you can use SwaggerFeature instead of Swagger2Feature (for CXF versions <= 3.1.x).</p><p>These features can be configured programatically in Java or using Spring or Blueprint beans.</p><h1 id="Swagger2Feature-Setup">Setup</h1><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> |
| <pre class="brush: xml; gutter: false; theme: Default"><dependency> |
| <groupId>org.apache.cxf</groupId> |
| <artifactId>cxf-rt-rs-service-description-swagger</artifactId> |
| <version>3.1.11</version> |
| </dependency> |
| |
| </pre> |
| </div></div><p>Note that a <strong>cxf-rt-rs-service-description</strong> needs to be used if older CXF 3.1.x versions are used.</p><p><br clear="none"></p><h1 id="Swagger2Feature-Properties">Properties</h1><p><span style="line-height: 1.4285715;">The following optional parameters can be configured in Swagger2Feature</span></p><p><span style="line-height: 1.4285715;">Note some properties listed below are not available or used differently in SwaggerFeature, as the corresponding properties are used differently in Swagger 2.0 and Swagger 1.2. Please refer to the corresponding Swagger documentation for more information.)</span></p><div class="table-wrap"><table class="wrapped confluenceTable"><colgroup span="1"><col span="1"><col span="1"><col span="1"></colgroup><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh">Name</th><th colspan="1" rowspan="1" class="confluenceTh">Description</th><th colspan="1" rowspan="1" class="confluenceTh">Default</th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">basePath</td><td colspan="1" rowspan="1" class="confluenceTd">the context root path<sup>+</sup></td><td colspan="1" rowspan="1" class="confluenceTd">null</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">contact</td><td colspan="1" rowspan="1" class="confluenceTd">the contact information<span>+</span></td><td colspan="1" rowspan="1" class="confluenceTd">null (in CXF 3.1.x "users@cxf.apache.org")</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">description</td><td colspan="1" rowspan="1" class="confluenceTd">the description<span>+</span></td><td colspan="1" rowspan="1" class="confluenceTd">null (in CXF 3.1.x "The Application")</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">filterClass</td><td colspan="1" rowspan="1" class="confluenceTd">a security filter<span>+</span></td><td colspan="1" rowspan="1" class="confluenceTd">null</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">host</td><td colspan="1" rowspan="1" class="confluenceTd">the host and port<span>+</span></td><td colspan="1" rowspan="1" class="confluenceTd">null</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">ignoreRoutes</td><td colspan="1" rowspan="1" class="confluenceTd">excludes specific paths when scanning all resources (see scanAllResources)<span>+</span><span>+</span></td><td colspan="1" rowspan="1" class="confluenceTd">null</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">license</td><td colspan="1" rowspan="1" class="confluenceTd">the license<span>+</span></td><td colspan="1" rowspan="1" class="confluenceTd">"Apache 2.0 License"</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">licenceUrl</td><td colspan="1" rowspan="1" class="confluenceTd">the license URL<span>+</span></td><td colspan="1" rowspan="1" class="confluenceTd">"<span class="nolink">http://www.apache.org/licenses/LICENSE-2.0.html</span>"</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">prettyPrint</td><td colspan="1" rowspan="1" class="confluenceTd">when generating swagger.json, pretty-print the json document<span>+</span></td><td colspan="1" rowspan="1" class="confluenceTd">false</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">resourcePackage</td><td colspan="1" rowspan="1" class="confluenceTd">a list of comma separated package names where resources must be scanned<span>+</span></td><td colspan="1" rowspan="1" class="confluenceTd">a list of service classes configured at the endpoint</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">runAsFilter</td><td colspan="1" rowspan="1" class="confluenceTd">runs the feature as a filter</td><td colspan="1" rowspan="1" class="confluenceTd">false</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">scan</td><td colspan="1" rowspan="1" class="confluenceTd">generates the swagger documentation<span>+</span></td><td colspan="1" rowspan="1" class="confluenceTd">true</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">scanAllResources</td><td colspan="1" rowspan="1" class="confluenceTd">scans all resources including non-annotated JAX-RS resources<span>+</span><span>+</span></td><td colspan="1" rowspan="1" class="confluenceTd">false</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">schemes</td><td colspan="1" rowspan="1" class="confluenceTd">the protocol schemes<span>+</span></td><td colspan="1" rowspan="1" class="confluenceTd">null</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">termsOfServiceUrl</td><td colspan="1" rowspan="1" class="confluenceTd">the terms of service URL<span>+</span></td><td colspan="1" rowspan="1" class="confluenceTd">null</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">title</td><td colspan="1" rowspan="1" class="confluenceTd">the title<span>+</span></td><td colspan="1" rowspan="1" class="confluenceTd">null (in CXF 3.1.x "Sample REST Application")</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">version</td><td colspan="1" rowspan="1" class="confluenceTd">the version<span>+</span></td><td colspan="1" rowspan="1" class="confluenceTd">null (in CXF 3.1.x "1.0.0")</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><span class="blob-code-inner blob-code-marker-addition">swaggerUiConfig</span></td><td colspan="1" rowspan="1" class="confluenceTd">Swagger UI configuration</td><td colspan="1" rowspan="1" class="confluenceTd">null</td></tr></tbody></table></div><p>Note: those descriptions marked with <span>+ correspond to the properties defined in Swagger's BeanConfig, and those marked with <span>+</span><span>+ correspond to the properties defined in Swagger's ReaderConfig.</span></span></p><h1 id="Swagger2Feature-ConfiguringfromCode">Configuring from Code</h1><p><br clear="none"></p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> |
| <pre class="brush: java; gutter: false; theme: Default">import org.apache.cxf.frontend.ServerFactoryBean; |
| import org.apache.cxf.jaxrs.swagger.Swagger2Feature; |
| ... |
| |
| Swagger2Feature feature = new Swagger2Feature(); |
| |
| // customize some of the properties |
| feature.setBasePath("/api"); |
| |
| // add this feature to the endpoint (e.g., to ServerFactoryBean's features) |
| ServerFactoryBean sfb = new ServerFactoryBean(); |
| sfb.getFeatures().add(feature);</pre> |
| </div></div><p><br clear="none"></p><h1 id="Swagger2Feature-ConfiguringinSpring">Configuring in Spring</h1><p><br clear="none"></p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> |
| <pre class="brush: java; gutter: false; theme: Default"><beans xmlns="http://www.springframework.org/schema/beans" |
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:cxf="http://cxf.apache.org/core" |
| xmlns:jaxrs="http://cxf.apache.org/jaxrs" |
| 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.swagger.server.Sample" /> |
| |
| <!-- CXF Swagger2Feature --> |
| <bean id="swagger2Feature" class="org.apache.cxf.jaxrs.swagger.Swagger2Feature"> |
| <!-- customize some of the properties --> |
| <property name="basePath" value="/app/swaggerSample"/> |
| </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="swagger2Feature" /> |
| </jaxrs:features> |
| </jaxrs:server> |
| </beans> |
| |
| </pre> |
| </div></div><p><br clear="none"></p><h1 id="Swagger2Feature-ConfiguringinBlueprint">Configuring in Blueprint</h1><p><br clear="none"></p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> |
| <pre class="brush: java; gutter: false; theme: Default"><blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0" |
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xmlns:cxf="http://cxf.apache.org/blueprint/core" |
| 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.swagger.server.Sample" /> |
| |
| |
| <!-- CXF Swagger2Feature --> |
| <bean id="swagger2Feature" class="org.apache.cxf.jaxrs.swagger.Swagger2Feature"> |
| <!-- customize some of the properties --> |
| <property name="basePath" value="/cxf/swaggerSample"/> |
| </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="swagger2Feature" /> |
| </jaxrs:features> |
| </jaxrs:server> |
| </blueprint> |
|  </pre> |
| </div></div><h1 id="Swagger2Feature-ConfiguringinCXFNonSpringJaxrsServlet">Configuring in CXFNonSpringJaxrsServlet</h1><p><br clear="none"></p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> |
| <pre class="brush: java; gutter: false; theme: Default"><web-app> |
| <context-param> |
| <param-name>contextParam</param-name> |
| <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.swagger.Swagger2Feature |
| (basePath=/somepath) |
| </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="Swagger2Feature-New:ConfiguringfromPropertiesfile">New: Configuring from Properties file</h1><p>Starting from CXF 3.1.13 and 3.2.0 it is possible to configure Swagger2Feature with a Properties file.</p><p>For example, while a <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/spring_boot" rel="nofollow">samples/jax_rs/spring_boot</a> demo configures the feature <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/distribution/src/main/release/samples/jax_rs/spring_boot/src/main/java/sample/rs/service/SampleRestApplication.java#L54" rel="nofollow">from the code</a>, a  <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/spring_boot_scan" rel="nofollow">samples/jax_rs/spring_boot_scan</a> demo has it configured from <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/distribution/src/main/release/samples/jax_rs/spring_boot_scan/application/src/main/resources/swagger.properties" rel="nofollow">the properties file</a>.</p><p>Default location for a properties file is "<strong>/swagger.properties</strong>". Swagger2Feature will pick it up if it is available, and the location can be overridden with a new Swagger2Feature '<strong>swaggerPropertiesLocation</strong>' property. </p><p>Note that the properties, if available, do not override the properties which may have been set as suggested above from the code or Spring/Blueprint contexts or web.xml. Instead they complement and serve as the default configuration properties: for example, if some properties have been set from the code then the values for the same properties found in the properties file will not be used.</p><h1 id="Swagger2Feature-EnablinginSpringBoot">Enabling in Spring Boot</h1><p>See <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/spring_boot" rel="nofollow">samples/jax_rs/spring_boot</a> and on how to create Swagger2Feature in a @Bean method or/and <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/distribution/src/main/release/samples/jax_rs/spring_boot_scan/application/src/main/resources/application.yml#L13" rel="nofollow"><span class="inline-comment-marker" data-ref="95051881-e36a-491b-bc40-392fdb95feb0">samples/jax_rs/spring_boot_scan</span></a> on how to auto-enable it.</p><p><br clear="none"></p><h1 id="Swagger2Feature-AccessingSwaggerDocuments">Accessing Swagger Documents</h1><p>When Swagger is enabled by Swagger feature, the Swagger documents will be available at the location URL constructed of the service endpoint location followed by /swagger.json or /swagger.yaml.</p><p>For example, lets assume a JAX-RS endpoint is published at 'http://host:port/context/services/' where 'context' is a web application context,  "/services" is a servlet URL. In this case its Swagger documents are available at 'http://host:port/context/services/swagger.json' and 'http://host:port/context/services/swagger.yaml'.</p><p>Starting from CXF 3.1.7 the CXF Services page will link to Swagger documents if Swagger2Feature is active. </p><p>In the above example, go to '<span>http://host:port/context/services/</span>services' and follow a Swagger link which will return a Swagger JSON document.</p><p>If <a shape="rect" class="external-link" href="https://github.com/swagger-api/swagger-ui/blob/master/README.md#cors-support" rel="nofollow">CORS support</a> is needed to access the definition from a Swagger UI on another host, the <a shape="rect" href="jax-rs-cors.html">CrossOriginResourceSharingFilter from cxf-rt-rs-security-cors</a> can be added.</p><p><br clear="none"></p><h1 id="Swagger2Feature-EnablingSwaggerUI">Enabling Swagger UI</h1><p>First one needs to add the following</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> |
| <pre class="brush: xml; gutter: false; theme: Default"><dependency> |
| <groupId>org.webjars</groupId> |
| <artifactId>swagger-ui</artifactId> |
| <version>2.2.10-1</version> |
| </dependency> |
| |
| </pre> |
| </div></div><p>The newest version 3.x of swagger-ui can also be used.</p><h2 id="Swagger2Feature-EnablingSwaggerUIinOSGicontainer(Karaf)">Enabling Swagger UI in OSGi container (Karaf)</h2><p>Since <strong>org.webjars</strong>/<strong>swagger-ui</strong> is just a package with resources, it won't be referenced in OSGi manifest as the required imports. Therefore, to make use of Swagger UI in the OSGi deployments, the <strong>org.webjars</strong>/<strong>swagger-ui</strong> should be installed manually, for example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> |
| <pre class="brush: java; gutter: false; theme: Default">karaf@root()> install mvn:org.webjars/swagger-ui/3.23.8</pre> |
| </div></div><p>The dedicated Activator will take care of discovering the presence of the <strong>org.webjars</strong>/<strong>swagger-ui</strong> bundle and configuring <strong>Swagger2Feature</strong>.</p><h2 id="Swagger2Feature-AutomaticUIActivation">Automatic UI Activation</h2><p>This feature is available starting from CXF 3.1.7: Adding a Swagger UI Maven dependency is all what is needed to start accessing Swagger documents with the help of Swagger UI.</p><p>For example, lets assume a JAX-RS endpoint is published at '<span>http://host:port/context/services/</span>'.</p><p>Open the browser and go to <span class="inline-comment-marker" data-ref="d7668130-e6ae-4083-a77a-cdfeb10de81e">'</span><span><span class="inline-comment-marker" data-ref="d7668130-e6ae-4083-a77a-cdfeb10de81e">http://host:port/context/services/</span></span><span class="inline-comment-marker" data-ref="d7668130-e6ae-4083-a77a-cdfeb10de81e">api-docs/?url=/swagger.json'</span> which will return a Swagger UI page.</p><p>CXF Services page will also link to Swagger UI. Go to '<span>http://host:port/context/services/</span>services' and follow a Swagger link which will return a Swagger UI page.</p><p>See <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger2" rel="nofollow">samples/jax_rs/description_swagger2</a>, <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger2_web" rel="nofollow">samples/jax_rs/description_swagger2_web</a>, <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/spring_boot" rel="nofollow">samples/jax_rs/spring_boot</a> and <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/spring_boot_scan" rel="nofollow">samples/jax_rs/spring_boot_scan</a> </p><p>Note that CXF OSGI endpoints can only depend on this feature starting from CXF 3.1.8.</p><h2 id="Swagger2Feature-UnpackingSwaggerUIresources">Unpacking Swagger UI resources</h2><p>Up until CXF 3.1.7 unpacking Swagger UI resources into the local folder was the only option. It is demoed in <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger2_spring" rel="nofollow">samples/jax_rs/description_swagger2_spring</a> and <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger2_osgi" rel="nofollow">samples/jax_rs/description_swagger2_osgi</a>.</p><p>In CXF 3.1.8: set Swagger2Feature 'supportSwaggerUi' property to 'false' to disable the automatic UI activation described in the previous section</p><h2 id="Swagger2Feature-ConfiguringSwaggerUI(3.2.7+)">Configuring Swagger UI (3.2.7+)</h2><p>The <strong>Swagger2Feature</strong>  has a way to pre-configure certain  Swagger UI parameters (<a shape="rect" class="external-link" href="https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md" rel="nofollow">https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md</a>) through <strong><span class="blob-code-inner blob-code-marker-addition"><span class="pl-smi">SwaggerUiConfig</span></span></strong><span class="blob-code-inner blob-code-marker-addition">. The</span><strong><span class="blob-code-inner blob-code-marker-addition"> </span></strong>way it is implemented is by passing those parameters as a query string so the Swagger UI could adjust itself.</p><h1 id="Swagger2Feature-ReverseProxy">Reverse Proxy</h1><p>Set a CXFServlet init parameter 'use-x-forwarded-headers' to 'true' if you access Swagger JSON and/or UI via the reverse proxy. If you use CXF SpringBoot starters then this property is prefixed with a "cxf.servlet.init.", "cxf.servlet.init.use-x-forwarded-headers".</p><p>You may also need to set Swagger2Feature 'usePathBasedConfig' property to 'true' to prevent Swagger from caching the 'basePath' value.</p><h1 id="Swagger2Feature-ConvertingtoOpenAPIJSON">Converting to OpenAPI JSON</h1><p><a shape="rect" class="external-link" href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md" rel="nofollow">OpenAPI specification</a> has been released and the CXF team has started working on the new feature which will produce OpenAPI JSON with the help of the new core and jaxrs libraries being currently developed by the Swagger community.</p><p>In meantime, while the new feature development is taking place, one can experiment with converting the Swagger JSON produced by CXF Swagger2Feature into Open API JSON.</p><p>All what is needed is registering <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/description-swagger/src/main/java/org/apache/cxf/jaxrs/swagger/openapi/SwaggerToOpenApiConversionFilter.java" rel="nofollow">SwaggerToOpenApiConversionFilter</a> with the JAX-RS endpoint and requesting an "openapi.json" as opposed to "swagger.json". The filter will let Swagger2Feature generate JSON as usual and then convert the response to OpenAPI JSON if requested by the user or leave it intact otherwise. By issuing either "swagger.json" or "openapi.json" queries one can easily see the difference  between the two formats.</p><p>The cxf-rt-rs-json-basic dependency must be on the classpath as well.</p><p><span class="inline-comment-marker" data-ref="0182cc9a-9bcb-467e-ba6e-ecea683448e8">Note, <a shape="rect" class="external-link" href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md" rel="nofollow">OpenAPI JSON</a></span> (see also <a shape="rect" href="openapifeature.html">OpenApiFeature</a>) allows referring to its new "components/requestBodies" section from the multiple "requestBody" elements (which can be found under the specific path/http verb sub-sections). By default the filter will instead inline the the "requestBody" definitions inside of "requestBody" elements, but one can experiment with referring to the "components/requestBodies" by <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/description-swagger/src/main/java/org/apache/cxf/jaxrs/swagger/openapi/OpenApiConfiguration.java" rel="nofollow">configuring</a> <a shape="rect" class="external-link" href="https://github.com/apache/cxf/blob/master/rt/rs/description-swagger/src/main/java/org/apache/cxf/jaxrs/swagger/openapi/SwaggerToOpenApiConversionFilter.java#L63" rel="nofollow">the filter</a> to create the request bodies.   </p><p>The conversion filter is available starting from CXF 3.1.15 and 3.2.2</p><h1 id="Swagger2Feature-Samples">Samples</h1><p><span>CXF's distribution contains the following samples.</span></p><ul><li><a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger" rel="nofollow">samples/jax_rs/description_swagger</a>: Swagger 1.2 sample using SwaggerFeature programatically</li><li><a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger2" rel="nofollow">samples/jax_rs/description_swagger2</a>: Swagger 2.0 standalone sample using Swagger2Feature programatically</li><li><a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger2_spring" rel="nofollow">samples/jax_rs/description_swagger2_spring</a>: Swagger 2.0 standalone sample using Swagger2Feature using Spring</li><li><a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger2_web" rel="nofollow">samples/jax_rs/description_swagger2_web</a>: Swagger 2.0 web application sample using Swagger2Feature using Spring</li><li><a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger2_osgi" rel="nofollow">samples/jax_rs/description_swagger2_osgi</a>: Swagger 2.0 OSGi application sample using Swagger2Feature using Blueprint<br clear="none"><br clear="none"></li></ul><p><br clear="none"></p></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=61318164">edit page</a>) |
| (<a href="https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=61318164&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> |
| |
