cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r1025376 - in /websites/production/cxf/content: cache/docs.pageCache docs/swagger2feature.html
Date Wed, 14 Feb 2018 10:57:29 GMT
Author: buildbot
Date: Wed Feb 14 10:57:29 2018
New Revision: 1025376

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 Wed Feb 14 10:57:29 2018
@@ -118,11 +118,11 @@ Apache CXF -- Swagger2Feature
            <!-- Content -->
            <div class="wiki-content">
 <div id="ConfluenceContent"><h1 id="Swagger2Feature-Swagger2Feature">Swagger2Feature</h1><p><style
type="text/css">/*<![CDATA[*/
-div.rbtoc1513025817588 {padding: 0px;}
-div.rbtoc1513025817588 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1513025817588 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1518605810440 {padding: 0px;}
+div.rbtoc1518605810440 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1518605810440 li {margin-left: 0px;padding-left: 0px;}
 
-/*]]>*/</style></p><div class="toc-macro rbtoc1513025817588">
+/*]]>*/</style></p><div class="toc-macro rbtoc1518605810440">
 <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><l
 i><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-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>
@@ -260,7 +260,7 @@ import org.apache.cxf.jaxrs.swagger.Swag
 &lt;/dependency&gt;
 
 </pre>
-</div></div><p>The newest version 3.x of swagger-ui can also be used.</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>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&#160;'<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>,&#1
 60;<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>&#160;</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/mas
 ter/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><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="Sw
 agger2Feature-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&#160; between the two formats.</p><p>Note,
OpenAPI JSON 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&#160;"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.&#160; &#160;</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>:&#160;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>:&#160;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>:&#160;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>:&#160;Swagger 2.0
OSGi application sample using Swagger2Feature using Blueprint<br clear="none"><br
clear="none"></li></ul><p>&#160;</p></div>
+</div></div><p>The newest version 3.x of swagger-ui can also be used.</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>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&#160;'<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>,&#1
 60;<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>&#160;</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/mas
 ter/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><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="Sw
 agger2Feature-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&#160; between the two formats.</p><p>The
cxf-rt-rs-json-basic dependency must be on the classpath as well.</p><p>Note,
OpenAPI JSON 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&#160;"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="exte
 rnal-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.&#160; &#160;</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>:&#160;Swagger 2.0 standalone
sample using Swagger2Feature progra
 matically</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>:&#160;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>:&#160;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>:&#160;Swagger 2.0
OSGi application sample using Swagger2Feature using Blueprint<br clear="none"><br
clear="none"></li></ul><p>&#160;</p></div>
            </div>
            <!-- Content -->
          </td>



Mime
View raw message