cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r1006932 - in /websites/production/cxf/content: cache/docs.pageCache docs/jaxrs-services-description.html
Date Fri, 17 Feb 2017 14:47:38 GMT
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>&#160;</p><p>&#160;</p><p>&#160;</p><p>&#160;</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:
   &lt;version&gt;3.0.0-milestone1&lt;/version&gt;
 &lt;/dependency&gt;
 </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
 --&gt;
 &lt;representation mediaType="application/xml" element="prefix1:thebook2"/&gt;
 </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>&#160;</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>&#160;</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;">&lt;groupId&gt;org.apache.cxf&lt;/groupId&gt;
 &lt;artifactId&gt;cxf-java2wadl-plugin&lt;/artifactId&gt;
 &lt;version&gt;3.0.0&lt;/version&gt;



Mime
View raw message