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 2017/02/17 14:47:38 UTC
svn commit: r1006932 - in /websites/production/cxf/content:
cache/docs.pageCache docs/jaxrs-services-description.html
Author: buildbot
Date: Fri Feb 17 14:47:38 2017
New Revision: 1006932
Log:
Production update by buildbot for cxf
Modified:
websites/production/cxf/content/cache/docs.pageCache
websites/production/cxf/content/docs/jaxrs-services-description.html
Modified: websites/production/cxf/content/cache/docs.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/cxf/content/docs/jaxrs-services-description.html
==============================================================================
--- websites/production/cxf/content/docs/jaxrs-services-description.html (original)
+++ websites/production/cxf/content/docs/jaxrs-services-description.html Fri Feb 17 14:47:38 2017
@@ -118,11 +118,11 @@ Apache CXF -- JAXRS Services Description
<!-- Content -->
<div class="wiki-content">
<div id="ConfluenceContent"><p><span class="inline-first-p" style="font-size:2em;font-weight:bold">JAX-RS Services Description</span> </p><p> </p><p> </p><p> </p><p><style type="text/css">/*<![CDATA[*/
-div.rbtoc1487339236292 {padding: 0px;}
-div.rbtoc1487339236292 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1487339236292 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1487342825306 {padding: 0px;}
+div.rbtoc1487342825306 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1487342825306 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1487339236292">
+/*]]>*/</style></p><div class="toc-macro rbtoc1487342825306">
<ul class="toc-indentation"><li><a shape="rect" href="#JAXRSServicesDescription-Swagger">Swagger</a>
<ul class="toc-indentation"><li><a shape="rect" href="#JAXRSServicesDescription-Swagger-FirstDevelopment">Swagger-First Development</a></li><li><a shape="rect" href="#JAXRSServicesDescription-SwaggerAutoGeneration">Swagger Auto Generation</a></li></ul>
</li><li><a shape="rect" href="#JAXRSServicesDescription-WADL">WADL</a>
@@ -337,7 +337,7 @@ div.rbtoc1487339236292 li {margin-left:
<version>3.0.0-milestone1</version>
</dependency>
</pre>
-</div></div><p>CXF JAX-RS supports the auto-generation of WADL for JAX-RS endpoints. <br clear="none"> Note that JAX-RS subresources are late-resolved by default, so using annotated interfaces for subresources and a staticSubresourceResolution=true property will let the whole resource tree/graph be described in a generated instance. Schemas will be generated for JAXB-annotated types. See below for the information on how to get auto-generated WADL instances reference existing schemas.</p><p><strong>CXF 2.4.0</strong>: org.apache.cxf.jaxrs.ext.Description and org.apache.cxf.jaxrs.ext.xml.XMLName have been moved to org.apache.cxf.jaxrs.model.wadl package given that their purpose is to improve the WADL generation. Also, org.apache.cxf.jaxrs.model.wadl.WadlElement has been renamed to 'ElementClass'.</p><h3 id="JAXRSServicesDescription-DocumentingresourceclassesandmethodsingeneratedWADL">Documenting resource classes and methods in generated WADL</h3><p>WADL documents can include <a shape=
"rect" class="external-link" href="http://www.w3.org/Submission/wadl/#x3-80002.3" rel="nofollow">doc</a> fragments.</p><p>Users may want to use <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/model/wadl/Description.java">Description</a> annotations which can be attached to resource classes and methods.</p><p>Note that starting from CXF 2.4.0, Description annotations can be applied to input parameters. Additionally, a method-level <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/model/wadl/Descriptions.java">Descriptions</a> annotation can have a collection of categorized Description annotations, with each Description targeting a specific WADL element by setting its 'target' property to one of the <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/ma
in/java/org/apache/cxf/jaxrs/model/wadl/DocTarget.java">DocTarget</a> values. For example, one can use a Descriptions annotation to document the response representation of a particular resource method, as well as add documentation fragments to WADL wadl:method/wadl:request and wadl:method/wadl:response elements:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>CXF JAX-RS supports the auto-generation of WADL for JAX-RS endpoints. <br clear="none"> Note that JAX-RS subresources are late-resolved by default, so using annotated interfaces for subresources and a staticSubresourceResolution=true property will let the whole resource tree/graph be described in a generated instance. Schemas will be generated for JAXB-annotated types. See below for the information on how to get auto-generated WADL instances reference existing schemas.</p><p><strong>CXF 2.4.0</strong>: org.apache.cxf.jaxrs.ext.Description and org.apache.cxf.jaxrs.ext.xml.XMLName have been moved to org.apache.cxf.jaxrs.model.wadl package given that their purpose is to improve the WADL generation. Also, org.apache.cxf.jaxrs.model.wadl.WadlElement has been renamed to 'ElementClass'.</p><h3 id="JAXRSServicesDescription-DocumentingresourceclassesandmethodsingeneratedWADL">Documenting resource classes and methods in generated WADL</h3><p>WADL documents can include <a shape=
"rect" class="external-link" href="http://www.w3.org/Submission/wadl/#x3-80002.3" rel="nofollow">doc</a> fragments.</p><p>Users may want to use <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/rt/rs/description/src/main/java/org/apache/cxf/jaxrs/model/wadl/Description.java" rel="nofollow">Description</a> annotations which can be attached to resource classes and methods.</p><p>Note that starting from CXF 2.4.0, Description annotations can be applied to input parameters. Additionally, a method-level <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/rt/rs/description/src/main/java/org/apache/cxf/jaxrs/model/wadl/Descriptions.java" rel="nofollow">Descriptions</a> annotation can have a collection of categorized Description annotations, with each Description targeting a specific WADL element by setting its 'target' property to one of the <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/m
aster/rt/rs/description/src/main/java/org/apache/cxf/jaxrs/model/wadl/DocTarget.java" rel="nofollow">DocTarget</a> values. For example, one can use a Descriptions annotation to document the response representation of a particular resource method, as well as add documentation fragments to WADL wadl:method/wadl:request and wadl:method/wadl:response elements:</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;">@POST
@Path("books/{bookid}")
@Descriptions({
@@ -359,7 +359,7 @@ public Book addBook(@Description("book i
@Path("books/{bookid}")
public Book addBook(@Description("book id") @PathParam("id") Long id) {...}
</pre>
-</div></div><h4 id="JAXRSServicesDescription-SupportforJavadoc">Support for Javadoc</h4><p>In CXF 3.0.0 one can get the Javadoc documentation copied to WADL being auto-generated at runtime.</p><p>org.apache.cxf.jaxrs.model.wadl.JavaDocProvider implements org.apache.cxf.jaxrs.model.wadl.DocumentationProvider and can be set as WADLGenerator "documentationProvider" property.</p><p>JavaDocProvider can be customized with URL or relative String path pointing to the generated Javadoc jar, so this jar can be shipped in the application war or located elsewhere.</p><p>JavaDocProvider parses the generated Javadoc HTML pages and scrapes the documentation. See Java to Wadl section on the alternative approach for supporting Javadoc.</p><h3 id="JAXRSServicesDescription-CustomizingWADLGeneration">Customizing WADL Generation</h3><p>One can register a custom WadlGenerator as a jaxrs:provider. The custom generator can extend the default <br clear="none"> org.apache.cxf.jaxrs.model.wadl.WadlGenerator o
r register a default one with one of the following properties set.</p><ul class="alternate"><li>wadlNamespace: default is "http://wadl.dev.java.net/2009/02", the earlier one is "http://research.sun.com/wadl/2006/10".</li><li>singleResourceMultipleMethods: default is 'true', for example, if a resource class has multiple methods supported at the same path such as "/" (GET, POST, etc) then WADL will list them all as the child nodes of a single resource element.</li><li>useSingleSlashResource: default is false, for example, if you have a root resource class with a path "root" and a resource method with a path "" or "/" then a WADL resource representing the root will not have a child resource representing this resource method (it would do if a resource method had a more specific path such as "bar").</li></ul><p>Starting from CXF 2.4.1 and 2.3.5 the following properties are also supported:</p><ul class="alternate"><li>applicationTitle: can be used to create an application title.</li><li>n
amespacePrefix: defaut is 'prefix', it can be set to other value such as 'ns'.</li><li>ignoreForwardSlash: can be used to enforce that resource path values do not start from '/'</li><li>addResourceAndMethodIds: WadlGenerator will add "id" attributes to wadl:resource and wadl:method elements</li></ul><p>An <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/model/wadl/ElementClass.java">ElementClass</a> annotation can help with representing JAX-RS Response elements in the generated WADL.</p><h4 id="JAXRSServicesDescription-RepresentingexplicitJAXBcollections">Representing explicit JAXB collections</h4><p>Starting from CXF 2.5.5 and 2.6.2 it is possible to get explicit collections represented in generated WADL grammar sections and have WADL representations linking to these schema elements. Note it is only possible for JAXB collections, for example:</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
+</div></div><h4 id="JAXRSServicesDescription-SupportforJavadoc">Support for Javadoc</h4><p>In CXF 3.0.0 one can get the Javadoc documentation copied to WADL being auto-generated at runtime.</p><p>org.apache.cxf.jaxrs.model.wadl.JavaDocProvider implements org.apache.cxf.jaxrs.model.wadl.DocumentationProvider and can be set as WADLGenerator "documentationProvider" property.</p><p>JavaDocProvider can be customized with URL or relative String path pointing to the generated Javadoc jar, so this jar can be shipped in the application war or located elsewhere.</p><p>JavaDocProvider parses the generated Javadoc HTML pages and scrapes the documentation. See Java to Wadl section on the alternative approach for supporting Javadoc.</p><h3 id="JAXRSServicesDescription-CustomizingWADLGeneration">Customizing WADL Generation</h3><p>One can register a custom WadlGenerator as a jaxrs:provider. The custom generator can extend the default <br clear="none"> org.apache.cxf.jaxrs.model.wadl.WadlGenerator o
r register a default one with one of the following properties set.</p><ul class="alternate"><li>wadlNamespace: default is "http://wadl.dev.java.net/2009/02", the earlier one is "http://research.sun.com/wadl/2006/10".</li><li>singleResourceMultipleMethods: default is 'true', for example, if a resource class has multiple methods supported at the same path such as "/" (GET, POST, etc) then WADL will list them all as the child nodes of a single resource element.</li><li>useSingleSlashResource: default is false, for example, if you have a root resource class with a path "root" and a resource method with a path "" or "/" then a WADL resource representing the root will not have a child resource representing this resource method (it would do if a resource method had a more specific path such as "bar").</li></ul><p>Starting from CXF 2.4.1 and 2.3.5 the following properties are also supported:</p><ul class="alternate"><li>applicationTitle: can be used to create an application title.</li><li>n
amespacePrefix: defaut is 'prefix', it can be set to other value such as 'ns'.</li><li>ignoreForwardSlash: can be used to enforce that resource path values do not start from '/'</li><li>addResourceAndMethodIds: WadlGenerator will add "id" attributes to wadl:resource and wadl:method elements</li></ul><p>An <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/rt/rs/description/src/main/java/org/apache/cxf/jaxrs/model/xml/ElementClass.java" rel="nofollow">ElementClass</a> annotation can help with representing JAX-RS Response elements in the generated WADL.</p><h4 id="JAXRSServicesDescription-RepresentingexplicitJAXBcollections">Representing explicit JAXB collections</h4><p>Starting from CXF 2.5.5 and 2.6.2 it is possible to get explicit collections represented in generated WADL grammar sections and have WADL representations linking to these schema elements. Note it is only possible for JAXB collections, 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" style="font-size:12px;">@GET
@Path("books")
@org.apache.cxf.jaxrs.model.xml.XMLName("{http://books}books")
@@ -381,7 +381,7 @@ wg.setSchemaLocations(Collections.single
-->
<representation mediaType="application/xml" element="prefix1:thebook2"/>
</pre>
-</div></div><p>If no JAXB is used then you can attach an <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/model/wadl/XMLName.java">XMLName</a> annotation to method input or output types. Alternatively, you can register an instance of <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/model/wadl/ElementQNameResolver.java">ElementQNameResolver</a> with the WadlGenerator which will be used for creating wadl:representation/@element values.</p><h4 id="JAXRSServicesDescription-Changingthebaseaddress">Changing the base address</h4><p>Starting from CXF 2.6.2 it is possible to affect the base address specified in the auto-generated WADL (in wadl:resources/@base attribute).<br clear="none"> WADLGenerator can be indirectly configured by setting a jaxrs:server/@publishedEndpointUrl attribute, similarly to the way CXF WS
DL generator can be configured by setting a jaxws:endpoint/@publishedEndpointUrl attribute.</p><p> </p><h2 id="JAXRSServicesDescription-java2wadlMavenplugin">java2wadl Maven plugin</h2><p>CXF 3.0.0 and 2.7.11 introduce java2wadl plugin for generating WADL at the build time:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>If no JAXB is used then you can attach an <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/rt/rs/description/src/main/java/org/apache/cxf/jaxrs/model/xml/XMLName.java" rel="nofollow">XMLName</a> annotation to method input or output types. Alternatively, you can register an instance of <a shape="rect" class="external-link" href="https://github.com/apache/cxf/tree/master/rt/rs/description/src/main/java/org/apache/cxf/jaxrs/model/wadl/ElementQNameResolver.java" rel="nofollow">ElementQNameResolver</a> with the WadlGenerator which will be used for creating wadl:representation/@element values.</p><h4 id="JAXRSServicesDescription-Changingthebaseaddress">Changing the base address</h4><p>Starting from CXF 2.6.2 it is possible to affect the base address specified in the auto-generated WADL (in wadl:resources/@base attribute).<br clear="none"> WADLGenerator can be indirectly configured by setting a jaxrs:server/@publishedEndpointUrl attribute
, similarly to the way CXF WSDL generator can be configured by setting a jaxws:endpoint/@publishedEndpointUrl attribute.</p><p> </p><h2 id="JAXRSServicesDescription-java2wadlMavenplugin">java2wadl Maven plugin</h2><p>CXF 3.0.0 and 2.7.11 introduce java2wadl plugin for generating WADL at the build time:</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;"><groupId>org.apache.cxf</groupId>
<artifactId>cxf-java2wadl-plugin</artifactId>
<version>3.0.0</version>