You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cxf.apache.org by bu...@apache.org on 2016/09/09 15:47:36 UTC
svn commit: r997043 - in /websites/production/cxf/content:
cache/docs.pageCache docs/swagger2feature.html
Author: buildbot
Date: Fri Sep 9 15:47:36 2016
New Revision: 997043
Log:
Production update by buildbot for cxf
Modified:
websites/production/cxf/content/cache/docs.pageCache
websites/production/cxf/content/docs/swagger2feature.html
Modified: websites/production/cxf/content/cache/docs.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/cxf/content/docs/swagger2feature.html
==============================================================================
--- websites/production/cxf/content/docs/swagger2feature.html (original)
+++ websites/production/cxf/content/docs/swagger2feature.html Fri Sep 9 15:47:36 2016
@@ -118,13 +118,23 @@ Apache CXF -- Swagger2Feature
<!-- Content -->
<div class="wiki-content">
<div id="ConfluenceContent"><h1 id="Swagger2Feature-Swagger2Feature">Swagger2Feature</h1><p><style type="text/css">/*<![CDATA[*/
-div.rbtoc1441806420055 {padding: 0px;}
-div.rbtoc1441806420055 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1441806420055 li {margin-left: 0px;padding-left: 0px;}
-
-/*]]>*/</style></p><div class="toc-macro rbtoc1441806420055">
-<ul class="toc-indentation"><li><a shape="rect" href="#Swagger2Feature-Swagger2Feature">Swagger2Feature</a></li><li><a shape="rect" href="#Swagger2Feature-Properties">Properties</a></li><li><a shape="rect" href="#Swagger2Feature-ConfiguringProgramatically">Configuring Programatically</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></ul>
-</div><p> </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.</p><p>These features can be configured programatically in Java or using Spring or Blueprint beans.</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.)</span></p><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh">Name</th><th colspan="1" rowspan="1" class="confluenceTh">Description</th><th colspan="1" rowspan="1" class="confluenceTh">Default</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">"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">"The Application"</td></tr><tr><t
d 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="conf
luenceTd">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">"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">"1.0.0"</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-ConfiguringProgramatically">Configuring Programatically</h1><p> </p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+div.rbtoc1473436020880 {padding: 0px;}
+div.rbtoc1473436020880 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1473436020880 li {margin-left: 0px;padding-left: 0px;}
+
+/*]]>*/</style></p><div class="toc-macro rbtoc1473436020880">
+<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-ConfiguringProgramatically">Configuring Programatically</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-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-AutomaticUIActivation">Automatic UI Activation</a></li><li><a shape="rect" href="#Swagger2Feature-UnpackingSwaggerUIresources">Unpacking Swagger UI resources</a></li></ul>
+</li><li><a shape="rect" href="#Swagger2Feature-Samples">Samples</a></li></ul>
+</div><p> </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.</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" style="font-size:12px;"><dependency>
+ <groupId>org.apache.cxf</groupId>
+ <artifactId>cxf-rt-rs-service-description-swagger</artifactId>
+ <version>3.1.7</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> </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="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh">Name</th><th colspan="1" rowspan="1" class="confluenceTh">Description</th><th colspan="1" rowspan="1" class="confluenceTh">Default</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">"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">"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 cols
pan="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 r
esources<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">"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">"1.0.0"</td></tr></tbody></ta
ble></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-ConfiguringProgramatically">Configuring Programatically</h1><p> </p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">import org.apache.cxf.frontend.ServerFactoryBean;
import org.apache.cxf.jaxrs.swagger.Swagger2Feature;
...
@@ -208,7 +218,49 @@ import org.apache.cxf.jaxrs.swagger.Swag
</jaxrs:server>
</blueprint>
 </pre>
-</div></div><p><span><span><br clear="none"></span></span></p><p> </p></div>
+</div></div><h1 id="Swagger2Feature-ConfiguringinCXFNonSpringJaxrsServlet">Configuring in CXFNonSpringJaxrsServlet</h1><p> </p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;"><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-EnablinginSpringBoot">Enabling in Spring Boot</h1><p>See <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/spring_boot" rel="nofollow">samples/jax_rs/spring_boot</a> and on how to create Swagger2Feature in a @Bean method and <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/spring_boot_scan" rel="nofollow">samples/jax_rs/spring_boot_scan</a> on how to auto-enable it.</p><p> </p><h1 id="Swagger2Feature-AccessingSwaggerDocuments">Accessing Swagger Documents</h1><p>When Swagger is enabled by Swagger feature, the Swagger documents will be available at the location URL constructed of the service endpoint location followed by /swagger.json or /swagger.yaml.</p><p>For example, lets assume a JAX-RS endpoint is published at 'http://host:port/context/services/' where 'context' is a web ap
plication 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><h1 id="Swagger2Feature-EnablingSwaggerUI">Enabling Swagger UI</h1><p>First one needs to add the following</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;"><dependency>
+ <groupId>org.webjars</groupId>
+ <artifactId>swagger-ui</artifactId>
+ <version>2.1.8-M1</version>
+</dependency>
+
+</pre>
+</div></div><h2 id="Swagger2Feature-AutomaticUIActivation">Automatic UI Activation</h2><p>This feature is available starting from CXF 3.1.7: Adding a Swagger UI Maven dependency is all what is needed to start accessing Swagger documents with the help of Swagger UI.</p><p>For example, lets assume a JAX-RS endpoint is published at '<span>http://host:port/context/services/</span>'.</p><p>Open the browser and go to '<span>http://host:port/context/services/</span>api-docs?/url=/swagger.json' which will return a Swagger UI page.</p><p>CXF Services page will also link to Swagger UI. Go to '<span>http://host:port/context/services/</span>services' and follow a Swagger link which will return a Swagger UI page.</p><p>See <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger2" rel="nofollow">samples/jax_rs/description_swagger2</a>, <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 has been the only option. It is demoed in all CXF Swagger demos but samples/jax_rs/description_swagger2 which</p><p>shows the automatic UI activation. In CXF 3.1.7: set Swagger2Feature 'supportSwaggerUi' property to 'false' to disable to automatic UI activation described in the previous section</p><h1 id="Swagger2Feature-Samples">Samples</h1><p><span>CXF's distribution contains the following sa
mples.</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/re
lease/samples/jax_rs/description_swagger2_web" rel="nofollow">samples/jax_rs/description_swagger2_web</a>: Swagger 2.0 web application sample using Swagger2Feature using Spring</li><li><a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/description_swagger2_osgi" rel="nofollow">samples/jax_rs/description_swagger2_osgi</a>: Swagger 2.0 OSGi application sample using Swagger2Feature using Blueprint<br clear="none"><br clear="none"></li></ul><p> </p></div>
</div>
<!-- Content -->
</td>