THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
| Span | |||
|---|---|---|---|
| Wiki Markup | |||
|
| ||
| } JAX-RS Services Description {span} {toc} CXF JAX-RS supports (Web Application Description Description |
| Table of Contents |
|---|
Swagger
Swagger-First Development
Swagger Auto Generation
Please see the Swagger2Feature page for more information
WADL
CXF JAX-RS supports (Web Application Description Language|http://www.w3.org/Submission/wadl]
...
(WADL).
...
Users
...
can
...
use
...
WADL
...
documents
...
to
...
generate
...
the
...
initial
...
code
...
and
...
have
...
WADL
...
auto-generated
...
on
...
demand.
...
Overview
WADL is a resource-centric
...
description
...
language
...
which
...
has
...
been
...
designed
...
to
...
facilitate
...
the
...
modeling,
...
description
...
and
...
testing
...
of
...
RESTful
...
Web
...
applications.
...
Please
...
check
...
the
...
official
...
...
for
...
more
...
information,
...
this
...
section
...
provides
...
a
...
brief
...
overview
...
of
...
main
...
WADL
...
constructs.
...
Basic
...
example
...
A
...
top
...
level
...
WADL
...
document
...
element
...
is
...
called
...
"application".
...
Usually
...
it
...
may
...
contain
...
a
...
"grammars"
...
section
...
and
...
"resources"
...
element
...
with
...
one
...
or
...
more
...
top-level
...
"resource"
...
elements,
...
with
...
each
...
one
...
representing
...
a
...
specific
...
root
...
resource,
...
for
...
example:
| Code Block | ||||
|---|---|---|---|---|
| ||||
{code:xml} <application xmlns="http://wadl.dev.java.net/2009/02" xmlns:ns="http://superbooks"> <grammars> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://superbooks" attributeFormDefault="unqualified" elementFormDefault="unqualified" targetNamespace="http://superbooks"> <xs:element name="thebook" type="tns:book"/> <xs:complexType name="book"> <xs:sequence> <xs:element minOccurs="0" ref="tns:thechapter"/> <xs:element name="id" type="xs:int"/> </xs:sequence> </xs:complexType> </xs:schema> </grammars> <resources base="http://localhost:8080/"> <resource path="/bookstore/{id}"> <param name="id" style="template"/> <method name="GET"> <response> <representation mediaType="application/xml" element="ns:thebook"/> </response> </method> </resource> <resource path="/books"> <resource path="/bookstore/{id}"> <param name="id" style="template"/> <method name="GET"> <response> <representation mediaType="application/xml" element="ns:thebook"/> </response> </method> </resource> </resource> </resources> </application> {code} This document describes an application that has |
This document describes an application that has "http://localhost:8080/"
...
base
...
URI.
...
It
...
can
...
handle
...
GET
...
requests
...
such
...
as
...
"http://localhost:8080/bookstore/1",
...
"http://localhost:8080/bookstore/123",
...
etc.
...
Additionally
...
it
...
can
...
handle
...
similar
...
GET
...
requests
...
at
...
"http://localhost:8080/books/bookstore/1",
...
"http://localhost:8080/books/bookstore/123",
...
etc,
...
note
...
an
...
extra
...
"books"
...
path
...
segment.
...
"application/xml"
...
media
...
type
...
is
...
supported
...
and
...
response
...
representation
...
elements
...
link
...
to
...
"
...
{http://superbooks}thebook"
...
element
...
declared
...
in
...
a
...
schema
...
inlined
...
in
...
the
...
grammars
...
section.
...
Note
...
that
...
"resources"
...
element
...
has
...
two
...
child
...
"resource"
...
elements,
...
one
...
with
...
"/bookstore/
...
{id}"
...
path,
...
another
...
one
...
with
...
"/books"
...
path.
...
These
...
2
...
resources
...
can
...
be
...
represented
...
as
...
JAX-RS
...
root
...
resources.
...
For
...
example,
...
these
...
resources
...
can
...
be
...
mapped
...
to
...
concrete
...
Java
...
classes
...
such
...
as
...
BookStoreRootResource
...
with
...
@Path("/bookstore/
...
{id}")
...
and
...
BooksResource
...
with
...
@Path("/books").
...
BookStoreRootResource
...
root
...
resource
...
will
...
have
...
a
...
single
...
@GET
...
resource
...
method
...
with
...
no
...
@Path,
...
presumably
...
returning
...
Book
...
(JAXB)
...
bean.
...
The
...
second
...
BooksResource
...
root
...
resource
...
will
...
have
...
a
...
single
...
subresource
...
locator
...
with
...
@Path("/bookstore/
...
{id}")
...
which
...
will
...
return
...
a
...
subresource
...
with
...
a
...
single
...
@GET
...
resource
...
method.
...
This
...
is
...
just
...
one
...
possible
...
interpretation
...
of
...
how
...
the
...
above
...
WADL
...
description
...
can
...
be
...
mapped
...
to
...
JAX-RS
...
resources
...
and
...
methods.
...
Also
...
note
...
that
...
the
...
resource
...
with
...
the
...
"/books"
...
path
...
has
...
another
...
child
...
resource
...
with
...
the
...
"/bookstore/
...
{id}"
...
path,
...
but
...
it
...
could've
...
had
...
a
...
"/books/bookstore/
...
{id}"
...
path
...
instead
...
and
...
no
...
child
...
resource.
...
WADL
...
with
...
references
...
Basic
...
WADL
...
example
...
in
...
the
...
previous
...
section
...
shows
...
a
...
"grammars"
...
section
...
with
...
the
...
inlined
...
schema,
...
as
...
well
...
as
...
a
...
"resource"
...
description
...
with
...
the
...
"/bookstore/
...
{id}"
...
path
...
listed
...
twice,
...
as
...
an
...
immediate
...
child
...
of
...
the
...
"resources"
...
and
...
as
...
a
...
child
...
of
...
the
...
"resource"
...
element
...
with
...
the
...
"/books"
...
path.
...
Note
...
that
...
inlined
...
schemas
...
can
...
be
...
included
...
instead
...
by
...
referencing
...
external
...
schemas.
...
Likewise,
...
most
...
of
...
WADL
...
element
...
declarations
...
such
...
as
...
"resource",
...
"method",
...
"representation",
...
etc
...
can
...
be
...
shared
...
by
...
using
...
the
...
same
...
document
...
or
...
external
...
references.
...
Here
...
is
...
how
...
the
...
basic
...
example
...
can
...
be
...
simplified
...
with
...
the
...
help
...
of
...
references:
| Code Block | ||||
|---|---|---|---|---|
| ||||
{code:xml} <application xmlns="http://wadl.dev.java.net/2009/02" xmlns:ns="http://superbooks"> <grammars> <include href="schemas/book.xsd"/> </grammars> <resource_type id="bookResource"> <param name="id" style="template"/> <method name="GET"> <response> <representation mediaType="application/xml" element="ns:thebook"/> </response> </method> </resource_type> <resources base="http://localhost:8080/"> <resource path="/bookstore/{id}" type="#bookResource"/> <resource path="/books"> <resource path="/bookstore/{id}" type="#bookResource"/> <!-- or <resource path="/books/bookstore/{id}" type="#bookResource"/> --> </resource> </resources> </application> {code} Note that a |
Note that a book.xsd
...
schema
...
resource
...
located
...
in
...
the
...
'schemas'
...
path
...
relative
...
to
...
the
...
location
...
of
...
this
...
WADL
...
document
...
is
...
referenced
...
using
...
wadl:include
...
element.
...
Abstract
...
resource
...
type
...
"bookResource"
...
is
...
declared
...
as
...
an
...
immediate
...
child
...
of
...
wadl:application
...
and
...
is
...
linked
...
to
...
concrete
...
resource
...
elements
...
using
...
a
...
"#bookResource"
...
reference.
...
Sharing
...
declarations
...
between
...
multiple
...
WADLs
...
WADL
...
references
...
allow
...
for
...
having
...
WADL
...
documents
...
with
...
abstract
...
declarations
...
only
...
and
...
concrete
...
WADLs
...
referencing
...
them,
...
thus
...
making
...
it
...
possible
...
to
...
reuse
...
resource
...
declarations
...
in
...
different
...
web
...
application
...
descriptions.
...
For
...
example,
...
the
...
following
...
baseApplication.wadl
...
documents
...
describes
...
an
...
abstract
...
"bookResource"
...
resource:
| Code Block | ||||
|---|---|---|---|---|
| ||||
{code:xml} <application xmlns="http://wadl.dev.java.net/2009/02" xmlns:ns="http://superbooks"> <grammars> <include href="schemas/book.xsd"/> </grammars> <resource_type id="bookResource"> <param name="id" style="template"/> <method name="GET"> <response> <representation mediaType="application/xml" element="ns:thebook"/> </response> </method> </resource_type> </application> {code} and this WADL document links to the abstract resource by using an external WADL reference with a "baseResource" fragment. {code:xml} |
and this WADL document links to the abstract resource by using an external WADL reference with a "baseResource" fragment.
| Code Block | ||||
|---|---|---|---|---|
| ||||
<application xmlns="http://wadl.dev.java.net/2009/02" xmlns:ns="http://superbooks">
<resources base="http://localhost:8080/">
<resource path="/bookstore/{id}" type="baseApplication.wadl#bookResource"/>
<resource path="/books">
<resource path="/bookstore/{id}" type="baseApplication.wadl#bookResource"/>
</resource>
</resources>
</application>
{code}
*New*: Starting from CXF |
New: Starting from CXF 2.5.0
...
and
...
2.4.4
...
all
...
WADL
...
elements
...
may
...
link
...
to
...
top-level
...
local
...
declarations,
...
see
...
this
...
...
.
WADL-first
...
Development
...
CXF
...
2.4.1
...
introduces
...
a
...
wadl2java
...
code
...
generator
...
and
...
cxf-wadl2java-plugin
...
Maven
...
plugin
...
which
...
can
...
be
...
used
...
to
...
generate
...
server
...
and
...
client
...
JAX-RS
...
code
...
and
...
speed
...
up
...
the
...
transition
...
between
...
modeling
...
and
...
implementation
...
stages.
...
Note If you are looking for a wadl2java code generator from a Java.net
...
project
...
started
...
by
...
Marc
...
Hadley
...
then
...
please
...
follow
...
this
...
link.
Code generator expects WADL resource and method elements to have "id" attributes set which can provide hints on how to name generated classes and methods. For example:
| Code Block | ||||
|---|---|---|---|---|
| ||||
|http://wadl.java.net/wadl2java.html]. Code generator expects WADL resource and method elements to have "id" attributes set which can provide hints on how to name generated classes and methods. For example: {code:xml} <application xmlns="http://wadl.dev.java.net/2009/02" xmlns:ns="http://superbooks"> <grammars> <include href="schemas/book.xsd"/> </grammars> <resources base="http://localhost:8080/"> <resource path="/bookstore/{id}" id="org.apache.cxf.jaxrs.systest.BookStore"> <param name="id" style="template"/> <method name="GET" id="getBook"> <response> <representation mediaType="application/xml" element="ns:thebook"/> </response> </method> </resource> </resources> </application> {code} |
Note
...
that
...
resource
...
id
...
is
...
"org.apache.cxf.jaxrs.systest.BookStore".
...
Alternatively,
...
expanded
...
QName
...
can
...
be
...
used
...
as
...
"id":
...
"
...
{http://systest.jaxrs.cxf.apache.org}BookStore".
...
Simple
...
WADL
...
documents
...
containing
...
a
...
single
...
resource
...
only
...
do
...
not
...
have
...
to
...
have
...
"id"
...
attributes
...
set.
...
In
...
such
...
cases
...
a
...
wadltojava
...
"resource"
...
and
...
"-p"
...
options
...
can
...
be
...
used
...
to
...
specify
...
a
...
full
...
root
...
resource
...
class
...
name
...
corresponding
...
to
...
a
...
single
...
WADL
...
resource
...
element,
...
and
...
if
...
neither
...
of
...
these
...
options
...
is
...
set
...
then
...
this
...
single
...
WADL
...
resource
...
will
...
get
...
an
...
"application.Resource"
...
root
...
resource
...
class
...
generated.
...
Note
...
that
...
the
...
code
...
generation
...
from
...
the
...
WADL
...
documents
...
containing
...
multiple
...
root
...
resources
...
with
...
no
...
"id"
...
attributes
...
is
...
supported
...
starting
...
from
...
CXF
...
2.5.0.
...
If
...
WADL
...
"method"
...
element
...
has
...
no
...
"id"
...
attribute
...
set
...
then
...
a
...
combination
...
of
...
the
...
element's
...
"name"
...
attribute
...
and
...
the
...
current
...
path
...
will
...
be
...
used
...
to
...
name
...
generated
...
class
...
methods,
...
example:
...
"getbookid",
...
where
...
the
...
method
...
name
...
is
...
"GET",
...
and
...
the
...
path
...
is
...
"/book/
...
{id}".
...
Classes
...
generated
...
from
...
schemas
...
will
...
have
...
a
...
package
...
name
...
derived
...
from
...
a
...
given
...
schema
...
target
...
namespace
...
by
...
default.
...
wadltojava
...
tool
...
lets
...
customize
...
it
...
as
...
well.
...
wadl2java
...
command
...
line
...
tool
...
Running
...
wadltojava
...
from
...
the
...
command
...
line
...
will
...
produce:
| No Format |
|---|
{noformat} wadl2java -p <package-name> -sp <[schema-namespace =]package-name>* -tMap <schema-type = java-type>* -repMap <media-type = java-type>* -resource <resource-name> -b <binding-file-name>* -catalog <catalog-file-name> -d <output-directory> -compile -classdir <compile-classes-directory> -interface -impl -noTypes -inheritResourceParams -generateEnums -supportMultipleXmlReps -javaDocs -generateResponseIfHeadersSet -generateResponseForMethods<methodNames>* -async<methodNames>* -xjc<xjc-arguments>* -rx <library> -authentication <name:password> -validate -h -v -verbose -quiet <wadl> {noformat} Note |
Note 'tMap',
...
'repMap',
...
'noTypes'
...
and
...
'inheritResourceParams'
...
options
...
are
...
supported
...
starting
...
from
...
CXF
...
2.6.3,
...
'noVoidForEmptyResponses'
...
-
...
from
...
2.6.4
...
, '-async' - from 2.7.1, '-xjc' - from 2.7.4,
'generateResponseForMethods' and 'generateResponseIfHeadersSet' - from 2.7.12/3.0.0, 'validate' - from 2.7.13/3.2.0/3.1.0, 'javaDocs' - from 3.1.4, 'authentication' - from 3.1.14/3.2.1, 'rx' - from 3.2.13/3.3.6.
The options are reviewed in the following table.
Option | Interpretation |
|---|---|
| Displays the online help for this utility and exits. |
| Specifies the package name of root resource classes |
| Specifies one or more package names corresponding to individual schema namespaces |
| Specifies a full name of root resource class if WADL contains a single resource |
| Default option unless -impl option is used - Java interfaces with JAX-RS annotations are generated |
| Generates starting implementation code. Can also be used with -interface option |
| Requests that no schema generation is needed. Can also be used with -tMap option |
| Provides mapping between schema elements and java types |
| Provides mapping between media types and java types |
| Specifies JAXB binding files. Use multiple -b flags to specify multiple entries. |
| Specifies catalog file to map referenced wadl/schemas |
| Specifies the directory into which the generated code files are written. |
| Compiles generated Java files. |
| Specifies the directory into which the compiled class files are written. |
| Generate JAX-RS Response instead of 'void' for methods with no response representations. |
| Get current resource-level path or matrix parameters added to generated methods for all descendant resources. |
| Generates Java enums for parameters with options. |
| Generates separate method for every XML representation in a single WADL request element. |
| -javaDocs | Converts WADL doc elements into JavaDocs |
| -generateResponseIfHeadersSet | Generates JAX-RS Response method response type if WADL response element for a given method has 'header' parameters |
| -generateResponseForMethods methodNames | Generates JAX-RS Response method response type, methodNames is a comma-separated list of WADL method name or id attributes |
| Adds JAX-RS 2.0 AsyncResponse parameter to generated methods, methodNames is a comma-separated list of WADL method name or id attributes |
| -authentication | Specifies a colon separated user name and password for retrieving the remote WADL content from the servers requiring the authentication |
| Specifies a comma separated list of arguments that are passed directly to the XJC processor, example -xjc-Xts. |
-rx <library> | Specifies the use of the JAX-RS 2.1 reactive extensions for generating method signatures. The supported <library> values are:
|
| -validate | Validate a WADL document against the WADL schema |
wadlurl | The path and name of the WADL file to use in generating the code. |
You must specify the absolute or relative path to the WADL document as the last argument.
OASIS catalog files can be used to help the tool resolve referenced WADL and schema documents.
Note 'tMap' option can be used to map between schema element references and java types and can be used to customize the default schema to Java type mapping. For example, in order to override a default parameter 'xs:date' to java.util.Date mapping one can do '-tMap {http://www.w3.org/2001/XMLSchema}date=javax.xml.datatype.XMLGregorianCalendar'
...
-
...
this
...
can
...
affect
...
the
...
"<wadl:param
...
type='xs:date'>"
...
declarations.
...
Alternatively,
...
in
...
combination
...
with
...
a
...
'-noTypes'
...
switch,
...
this
...
option
...
can
...
be
...
used
...
to
...
request
...
that
...
a
...
custom
...
Java
...
type
...
reference
...
should
...
be
...
generated.
...
For
...
example,
...
if
...
one
...
prefers
...
to
...
use
...
'javax.xml.transform.Source'
...
for
...
handling
...
a
...
given
...
XML
...
payload,
...
one
...
can
...
do
...
'-tMap
...
{http://book}Book=javax.xml.transform.Source',
...
this
...
will
...
affect
...
"<wadl:representation
...
element='ns:Book'>"
...
declarations
...
where
...
'ns'
...
prefix
...
is
...
bound
...
to
...
the
...
'http://book'
...
namespace.
...
Similarly,
...
a
...
schema
...
reference
...
to
...
Atom
...
Feed
...
element
...
can
...
be
...
mapped
...
to
...
say
...
Abdera
...
Feed
...
class.
...
The
...
'repMap'
...
option
...
is
...
similar
...
and
...
provides
...
a
...
mapping
...
between
...
the
...
representations
...
of
...
a
...
given
...
media
...
type
...
and
...
Java
...
type.
...
For
...
example,
...
if
...
one
...
has
...
to
...
process
...
different
...
XML
...
representations
...
in
...
one
...
method,
...
a
...
mapping
...
like
...
'-repMap
...
application/xml=javax.xml.transform.Source'
...
will
...
work,
...
affecting
...
declarations
...
like
...
"<wadl:representation
...
mediaTpe='application/xml'".
...
Similarly
...
CXF
...
org.apache.cxf.jaxrs.ext.multipart.MultipartBody
...
class
...
can
...
be
...
linked
...
to
...
'multipart/form-data'
...
representations, etc.
The 'generateResponseForMethods' and 'async' options accept a comma separated list of method names, providing a single '*' (no quotes) as a method name will get these options affecting all of the generated methods.
In some cases, example when describing JSON arrays, you may want to have an explicit collection of types defined in schema generated. In this case use -tMap or -repMap option with a value such as "List..MyType".
The reactive extensions support is limited to Java 8 standard library APIs only, which essentially means CompletionStage / CompletableFuture are supported at the moment. Please note that the void / one-way methods are not generated with CompletionStage / CompletableFuture and kept unchanged.
JAXB customizations
At the moment it is possible to apply external JAXB customizations to WADL grammars however it is not possible yet to restrict a given customization to a specific WADL document or explicitly inlined schema. Linking binding to external schemas works, for example, the following bindings file can be used:
| Code Block | ||||
|---|---|---|---|---|
| ||||
etc. h3. JAXB customizations At the moment it is possible to apply external JAXB customizations to WADL grammars however it is not possible yet to restrict a given customization to a specific WADL document or explicitly inlined schema. Linking binding to external schemas works, for example, the following bindings file can be used: {code:xml} <jaxb:bindings version="2.0" xmlns:jaxb="http://java.sun.com/xml/ns/jaxb" xmlns:xs="http://www.w3.org/2001/XMLSchema" schemaLocation="schemas/book.xsd" node="//xs:complexType[@name='book2']/xs:sequence/xs:element[@name='id']"> <jaxb:property name="book2Id"/> </jaxb:bindings> {code} h2. wadl2java Maven plugin If you need the code generated during Maven build then the following plugin can be used: {code:xml} |
wadl2java Maven plugin
If you need the code generated during Maven build then the following plugin can be used:
| Code Block | ||||
|---|---|---|---|---|
| ||||
<groupId>org.apache.cxf</groupId>
<artifactId>cxf-wadl2java-plugin</artifactId>
<version>2.4.1</version>
{code}
|
Add
...
this
...
plugin
...
to
...
the
...
build
...
section
...
of
...
your
...
project's
...
pom
...
and
...
specify
...
a
...
'wadl2java'
...
goal,
...
for
...
example:
| Code Block | ||||
|---|---|---|---|---|
| ||||
{code:xml} <build> <plugins> <plugin> <groupId>org.apache.cxf</groupId> <artifactId>cxf-wadl2java-plugin</artifactId> <version>2.4.1</version> <executions> <execution> <id>generate-sources</id> <phase>generate-sources</phase> <configuration> <sourceRoot>${basedir}/target/generated/src/main/java</sourceRoot> <wadlOptions> <wadlOption> <wadl>${basedir}/src/test/resources/wadl/bookstoreImport.xml</wadl> <impl>true</impl> <packagename>org.apache.cxf.systest.jaxrs.codegen.service</packagename> <schemaPackagenames> <schemaPackagename>http://superbooks=org.apache.cxf.systest.jaxrs.codegen.schema</schemaPackagename> </schemaPackagenames> </wadlOption> </wadlOptions> </configuration> <goals> <goal>wadl2java</goal> </goals> </execution> </executions> </plugin> </plugins> </build> {code} |
Note
...
that
...
the
...
minimum
...
and
...
maximum
...
memory
...
limits
...
may
...
need
...
to
...
be
...
increased
...
when
...
using
...
the
...
plugin
...
to
...
process
...
large
...
WADL
...
documents,
...
for
...
example,
...
add
...
"-Xms512M
...
-Xmx1024M"
...
to
...
the
...
list
...
of
...
Maven
...
options.
...
CXF
...
will
...
generate
...
artifacts
...
in
...
the
...
<sourceRoot>
...
directory.
...
Configuration
...
arguments
...
which
...
are
...
included
...
inside
...
the
...
<wadlOption>
...
element
...
are
...
used
...
to
...
pass
...
arguments
...
to
...
the
...
tooling
...
and
...
correspond
...
to
...
the
...
options
...
outlined
...
in
...
the
...
wadltojava
...
section,
...
they
...
can
...
be
...
specified
...
explicitly,
...
as
...
above,
...
or
...
using
...
an
...
"extraargs"
...
wrapper,
...
for
...
example:
| Code Block | ||||
|---|---|---|---|---|
| ||||
{code:xml} <wadlOptions> <wadlOption> <wadl>$\{basedir}/src/main/wadl/bookStore.wadl</wsdl> <extraargs> <extraarg>-impl</extraarg> <extraarg>-verbose</extraarg> </extraargs> </wadlOption> </wadlOptions> {code} h2. Integration Two options are available to developers who wish to integrate CXF JAX-RS WADLToJava code generator. First option is to pass the collected options directly to a wadltojava process. Another approach is to use |
Integration
Two options are available to developers who wish to integrate CXF JAX-RS WADLToJava code generator.
First option is to pass the collected options directly to a wadltojava process.
Another approach is to use org.apache.cxf.tools.wadlto.jaxrs.JAXRSContainer
...
class
...
shipped
...
with
...
the
...
cxf-tools-wadlto-jaxrs
...
module:
| Code Block | ||||
|---|---|---|---|---|
| ||||
{code:xml} <groupId>org.apache.cxf</groupId> <artifactId>cxf-tools-wadlto-jaxrs</artifactId> <version>2.4.1</version> {code} |
Please
...
see
...
CXF
...
source
...
for
...
more
...
details
...
and
...
org.apache.cxf.tools.wadlto.jaxrs.JAXRSContainerTest
...
in
...
particular.
External WADL documents and JAXRS endpoints.
External WADL documents can be linked to from jaxrs:server endpoints using newly introduced "docLocation" attribute, for example:
| Code Block | ||||
|---|---|---|---|---|
| ||||
h2. External WADL documents and JAXRS endpoints. External WADL documents can be linked to from jaxrs:server endpoints using newly introduced "docLocation" attribute, for example: {code:xml} <jaxrs:server address="/rest" docLocation="wadl/bookStore.wadl"> <jaxrs:serviceBeans> <bean class="org.bar.generated.BookStore"/> </jaxrs:serviceBeans> </jaxrs:server> {code} |
If
...
external
...
WADL
...
documents
...
include
...
external
...
schemas
...
and
...
jaxrs
...
endpoints
...
need
...
to
...
have
...
the
...
schema
...
validation
...
enabled,
...
then
...
those
...
schemas
...
can
...
be
...
referenced
...
in
...
the
...
jaxrs:schemaLocations
...
section
...
as
...
well.
...
WADL
...
Auto
...
Generation at Runtime
Note that in CXF 3.0.0 WADL Generator code has been moved to
| Code Block | ||||
|---|---|---|---|---|
| ||||
<dependency>
<groupId>org.apache.cxf</groupId>
<artifactId>cxf-rt-rs-service-description</artifactId>
<version>3.0.0-milestone1</version>
</dependency>
|
CXF JAX-RS supports the auto-generation of WADL for JAX-RS endpoints.
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.
CXF 2.4.0: 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'.
...
Documenting resource classes and methods in generated WADL
WADL documents can include doc fragments.
Users may want to use Description annotations which can be attached to resource classes and methods.
Note that starting from CXF 2.4.0, Description annotations can be applied to input parameters. Additionally, a method-level Descriptions 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 DocTarget 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:
| Code Block | ||||
|---|---|---|---|---|
| ||||
{code:java} @POST @Path("books/{bookid}") @Descriptions({ @Description(value = "Adds a new book", target = DocTarget.METHOD), @Description(value = "Requested Book", target = DocTarget.RETURN), @Description(value = "Request", target = DocTarget.REQUEST), @Description(value = "Response", target = DocTarget.RESPONSE), @Description(value = "Resource", target = DocTarget.RESOURCE) }) public Book addBook(@Description("book id") @PathParam("id") Long id, @Description("New Book") Book book) {...} {code} |
Every
...
unique
...
@Path
...
value
...
adds
...
a
...
new
...
'resource'
...
element
...
to
...
the
...
generated
...
WADL,
...
thus
...
the
...
last
...
Description
...
annotation
...
in
...
the
...
@Descriptions
...
array
...
ensures
...
the
...
doc
...
extension
...
is
...
also
...
added
...
to
...
the
...
'resource'
...
element.
...
Note
...
that
...
multiple
...
resource
...
methods
...
having
...
different
...
HTTP
...
methods
...
but
...
sharing
...
the
...
same
...
@Path
...
value
...
will
...
have
...
the
...
same
...
parent
...
'resource'
...
element
...
representing
...
this
...
shared
...
path
...
fragment,
...
in
...
this
...
case
...
a
...
Description
...
with
...
the
...
DocTarget.RESOURCE
...
target
...
will
...
be
...
ignored
...
unless
...
it
...
is
...
added
...
to
...
the
...
first
...
resource
...
method
...
with
...
this
...
shared
...
@Path:
| Code Block | ||||
|---|---|---|---|---|
| ||||
{code:java} @POST @Path("books/{bookid}") @Description(value = "Resource", target = DocTarget.RESOURCE), public Book addBook(@Description("book id") @PathParam("id") Long id, @Description("New Book") Book book) {...} @GET @Path("books/{bookid}") public Book addBook(@Description("book id") @PathParam("id") Long id) {...} {code} h2. Customizing WADL Generation One can register a custom WadlGenerator as a jaxrs:provider. The custom generator can extend the default |
Support for Javadoc
In CXF 3.0.0 one can get the Javadoc documentation copied to WADL being auto-generated at runtime.
org.apache.cxf.jaxrs.model.wadl.JavaDocProvider implements org.apache.cxf.jaxrs.model.wadl.DocumentationProvider and can be set as WADLGenerator "documentationProvider" property.
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.
JavaDocProvider parses the generated Javadoc HTML pages and scrapes the documentation. See Java to Wadl section on the alternative approach for supporting Javadoc.
Customizing WADL Generation
One can register a custom WadlGenerator as a jaxrs:provider. The custom generator can extend the default
org.apache.cxf.jaxrs.model.wadl.WadlGenerator or register a default one with one of the following properties set.
- wadlNamespace: default is "http://wadl.dev.java.net/2009/02", the earlier one is "http://research.sun.com/wadl/2006/10".
- 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.
- 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").
Starting from CXF 2.4.1 and 2.3.5 the following properties are also supported:
- applicationTitle: can be used to create an application title.
- namespacePrefix: defaut is 'prefix', it can be set to other value such as 'ns'.
- ignoreForwardSlash: can be used to enforce that resource path values do not start from '/'
- addResourceAndMethodIds: WadlGenerator will add "id" attributes to wadl:resource and wadl:method elements
An ElementClass annotation can help with representing JAX-RS Response elements in the generated WADL.
Representing explicit JAXB collections
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:
| Code Block | ||||
|---|---|---|---|---|
| ||||
WadlGenerator or register a default one with one of the following properties set. - wadlNamespace: default is "http://wadl.dev.java.net/2009/02", the earlier one is "http://research.sun.com/wadl/2006/10". - 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. - 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"). Starting from CXF 2.4.1 and 2.3.5 the following properties are also supported: - applicationTitle: can be used to create an application title. - namespacePrefix: defaut is 'prefix', it can be set to other value such as 'ns'. - ignoreForwardSlash: can be used to enforce that resource path values do not start from '/' - addResourceAndMethodIds: WadlGenerator will add "id" attributes to wadl:resource and wadl:method elements An [ElementClass|http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/model/wadl/ElementClass.java] annotation can help with representing JAX-RS Response elements in the generated WADL. h3. Representing explicit JAXB collections 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: {code:java} @GET @Path("books") @org.apache.cxf.jaxrs.model.wadlxml.XMLName("{http://books}books") public List<Book> getBooks() {...} {code} |
Given
...
the
...
above
...
example,
...
WADLGenerator
...
will
...
attempt
...
to
...
add
...
a
...
'books'
...
element
...
to
...
the
...
generated
...
schema
...
with
...
the
...
targetNamespace
...
set
...
to
...
"http://books".
...
This
...
'books'
...
element
...
will
...
have
...
a
...
sequence
...
of
...
elements
...
linking
...
to
...
a
...
type
...
representing
...
the
...
"Book"
...
class.
...
Representing
...
external
...
schemas
...
and
...
non
...
JAXB
...
types
...
By
...
default,
...
the
...
WADL
...
grammar
...
section
...
will
...
be
...
properly
...
generated
...
if
...
resource
...
methods
...
accept
...
or
...
return
...
JAXB
...
types.
...
Even
...
when
...
you
...
do
...
use
...
JAXB,
...
the
...
JAXB
...
types
...
may
...
have
...
been
...
generated
...
from
...
the
...
external
...
schema
...
so
...
having
...
WadlGenerator
...
attempting
...
to
...
recreate
...
the
...
original
...
schema
...
may
...
not
...
work
...
well.
...
To
...
have
...
a
...
generated
...
WADL
...
referencing
...
the
...
original
...
schema(s)
...
please
...
set
...
a
...
'schemaLocations'
...
list
...
property
...
(programmatically
...
or
...
from
...
Spring)
...
:
| Code Block | ||||
|---|---|---|---|---|
| ||||
{code:java} WadlGenerator wg = new WadlGenerator(); wg.setSchemaLocations(Collections.singletonList("classpath:/book.xsd")); {code} In this case the grammar section will have the |
In this case the grammar section will have the 'book.xsd'
...
schema
...
inlined.
...
If
...
this
...
schema
...
imports
...
other
...
schemas
...
then
...
the
...
imports
...
with
...
relative
...
URIs
...
will
...
be
...
replaced
...
by
...
the
...
absolute
...
URIs
...
based
...
on
...
the
...
current
...
endpoint's
...
base
...
address.
...
For
...
example,
...
if
...
the
...
endpoint
...
address
...
is
...
"http://somehost/bar"
...
and
...
the
...
'book.xsd'
...
imports
...
"foo/book1.xsd"
...
then
...
the
...
published
...
WADL
...
will
...
contain
...
an
...
"http://somehost/bar/foo/book1.xsd".
...
At
...
the
...
moment
...
a
...
custom
...
RequestHandler
...
filter
...
will
...
have
...
to
...
be
...
registered
...
to
...
serve
...
resources
...
such
...
as
...
"http://somehost/bar/foo/book1.xsd"
...
which
...
can
...
'calculate'
...
which
...
resource
...
is
...
required
...
get
...
the
...
absolute
...
request
...
URI
...
and
...
comparing
...
it
...
with
...
the
...
base
...
URI,
...
possibly
...
with
...
the
...
help
...
of
...
the
...
injected
...
JAXRS
...
UriInfo
...
context.
...
Alternatively,
...
resources
...
such
...
as
...
book1.xsd
...
may
...
be
...
served
...
by
...
CXFServlet
...
itself
...
(see
...
the
...
Redirection
...
with
...
CXFServlet)
...
TODO
...
:
...
add
...
ignoreImports
...
flag
...
so
...
that
...
users
...
can
...
list
...
root
...
and
...
imported
...
schemas
...
in
...
"schemaLocations"
...
and
...
have
...
them
...
all
...
inlined.
...
Note
...
that
...
the
...
root
...
schema
...
such
...
as
...
"book.xsd"
...
is
...
inlined
...
-
...
you
...
can
...
have
...
it
...
referenced
...
only
...
by
...
setting
...
an
...
'externalLinks'
...
list
...
property.
...
This
...
will
...
work
...
very
...
well
...
when
...
the
...
"book.xsd"
...
is
...
indeed
...
available
...
at
...
the
...
external
...
URI,
...
but
...
this
...
property
...
can
...
also
...
be
...
used
...
to
...
avoid
...
the
...
local
...
schemas
...
being
...
inlined.
...
Moreover,
...
the
...
use
...
of
...
JAXB
...
will
...
not
...
be
...
required.
...
The
...
result
...
will
...
look
...
like
...
this:
| Code Block | ||||
|---|---|---|---|---|
| ||||
{code:xml} <wadl:grammars> <wadl:include href="http://books.xsd"/> </wadl:grammars> {code} Note that |
Note that "schemaLocations"
...
and
...
"externalLinks"
...
properties
...
differ
...
in
...
that
...
the
...
schemas
...
referenced
...
by
...
the
...
former
...
one
...
are
...
inlined.
...
You
...
can
...
also
...
customize
...
the
...
way
...
schema
...
elements
...
are
...
referenced.
...
When
...
WadlGenerator
...
creates
...
WADL
...
representation
...
elements
...
(representing
...
resource
...
method
...
input
...
or
...
output
...
types)
...
it
...
will
...
be
...
able
...
to
...
link
...
to
...
schema
...
elements
...
provided
...
a
...
given
...
type
...
is
...
actually
...
a
...
JAXB
...
one,
...
so
...
the
...
result
...
may
...
look
...
like
...
this
...
:
| Code Block | ||||
|---|---|---|---|---|
| ||||
{code:xml} <!-- thebook2 element is declared in a schema inlined in or referenced from the grammar section prefix1 is bound to that schema's target namespace and is declared at the wadl:application element --> <representation mediaType="application/xml" element="prefix1:thebook2"/> {code} |
If
...
no
...
JAXB
...
is
...
used
...
then
...
you
...
can
...
attach
...
an XMLName annotation to method input or output types. Alternatively, you can register an instance of ElementQNameResolver with the WadlGenerator which will be used for creating wadl:representation/@element values.
Changing the base address
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).
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.
java2wadl Maven plugin
CXF 3.0.0 and 2.7.11 introduce java2wadl plugin for generating WADL at the build time:
| Code Block | ||||
|---|---|---|---|---|
| ||||
<groupId>org.apache.cxf</groupId>
<artifactId>cxf-java2wadl-plugin</artifactId>
<version>3.0.0</version>
|
Add this plugin to the build section of your project's pom, for example:
| Code Block | ||||
|---|---|---|---|---|
| ||||
<build>
<plugins>
<plugin>
<groupId>org.apache.cxf</groupId>
<artifactId>cxf-java2wadl-plugin</artifactId>
<version>3.0.0</version>
<executions>
<!-- Enable if support for Javadoc is required, not supported in CXF 2.7.11 -->
<!--
<execution>
<id>parsejavadoc</id>
<phase>generate-sources</phase>
<goals>
<goal>parsejavadoc</goal>
</goals>
</execution>
-->
<execution>
<id>process-classes</id>
<phase>process-classes</phase>
<goals>
<goal>java2wadl</goal>
</goals>
<configuration>
<classResourceNames>
<classResourceName>a.b.c.CustomerService</classResourceName>
</classResourceNames>
<!-- Enable if support for Javadoc is required, not supported in CXF 2.7.11 -->
<!--
<docProvider>org.apache.cxf.maven_plugin.javatowadl.ResourceMapJavaDocProvider</docProvider>
-->
<attachWadl>true</attachWadl>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
|
Note that Javadoc can be properly supported by enabling the "parsejavadoc" execution and a docProvider property.
WADL Transformations
Starting from CXF 3.0.4 it is possible to configure WADLGenerator with a 'stylesheetReference' property pointing to a local XSLT template.
If an 'applyStylesheetLocally' property is disabled (default) then a generated WADL XML representation will include an XML XSLT processing instruction pointing to a template with the browser downloading it in the next step and doing the transformation itself. Otherwise WADLGenerator will attempt to do a local transformation before returning a response to the browser.
This feature can help with further enhancing the generated WADL XML with some simple transformations (example, adding some information to WADL XML that is not possible to get from the annotated JAX-RS resources) or convert it to HTML.
Service listings and WADL queries
Links to WADL instances for RESTful endpoints are available from {base endpointaddress}/services, in addition to SOAP endpoints if any.
For example, given
| Code Block | ||||
|---|---|---|---|---|
| ||||
[XMLName|http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/model/wadl/XMLName.java] annotation to method input or output types. Alternatively, you can register an instance of [ElementQNameResolver|http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/model/wadl/ElementQNameResolver.java] with the WadlGenerator which will be used for creating wadl:representation/@element values. h3. Changing the base address 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). 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. h1. Service listings and WADL queries Links to WADL instances for RESTful endpoints are available from \{base endpointaddress\}/services, in addition to SOAP endpoints if any. For example, given {code:xml} Base address : 'http://localhost:8080' WAR name : 'store' CXFServlet : '/books/*' jaxrs:server/@address = '/orders' {code} |
and
...
visiting
...
>
...
http://localhost:8080/store/books
...
>
...
http://localhost:8080/store/books/services
...
will
...
let
...
you
...
see
...
all
...
the
...
WADL
...
links.
...
Note
...
that
...
you
...
can
...
override
...
the
...
location
...
at
...
which
...
listings
...
are
...
provided
...
(in
...
case
...
you
...
would
...
like
...
'/services'
...
be
...
available
...
to
...
your
...
resources)
...
using
...
'service-list-path'
...
CXFServlet
...
parameter,
...
example:
...
>
...
'service-list-path'
...
=
...
'/listings'
...
Going
...
to
...
the
...
service
...
listings
...
page
...
is
...
not
...
the
...
only
...
way
...
to
...
see
...
WADL
...
instances,
...
one
...
can
...
also
...
get
...
it
...
using
...
a
...
?_wadl
...
query.
...
>
...
http://localhost:8080/store/books/orders?_wadl
...
will
...
give
...
you
...
the
...
description
...
of
...
all
...
the
...
root
...
resource
...
classes
...
registered
...
with
...
a
...
given
...
jaxrs:server
...
endpoint.
...
For
...
example,
...
if
...
the
...
following
...
2
...
root
...
resource
...
classes
...
has
...
been
...
registered
...
with
...
this
...
endpoint:
| Code Block | ||||
|---|---|---|---|---|
| ||||
{code:java} @Path("/fiction") public class FictionBookOrders { } @Path("/sport") public class SportBookOrders { } {code} |
then
...
WADL
...
will
...
contain
...
the
...
description
...
of
...
both
...
FictionBookOrders
...
and
...
SportBookOrders
...
resources.
...
>
...
http://localhost:8080/store/books/orders/fiction?_wadl
...
>
...
http://localhost:8080/store/books/orders/sport?_wadl
...
will
...
give
...
you
...
all
...
the
...
info
...
for
...
FictionBookOrders
...
and
...
SportBookOrders
...
respectively.
...
Note
...
that
...
WadlGenerator
...
will
...
return
...
an
...
existing
...
WADL
...
document
...
instead
...
of
...
auto-generating
...
a
...
new
...
one
...
if
...
jaxrs:server/@docLocation
...
attribute
...
has
...
been
...
set.
...
By
...
default,
...
starting
...
from
...
CXF
...
2.5.1
...
and
...
2.4.5,
...
the
...
media
...
type
...
for
...
a
...
?_wadl
...
response
...
is
...
set
...
to
...
application/xml
...
which
...
is
...
to
...
do
...
with
...
the
...
fact
...
that
...
Firefox
...
does
...
not
...
really
...
like
...
'application/vnd.sun.wadl+xml'
...
unless
...
some
...
wadl
...
plugin
...
is
...
registered.
...
If
...
HTTP
...
Content-Type
...
is
...
set
...
to
...
'application/xml'
...
then
...
Firefox
...
will
...
show
...
it
...
with
...
no
...
problems.
...
You
...
can
...
easily
...
customize
...
what
...
Content-Type
...
is
...
set
...
by
...
either
...
using
...
a
...
WadlGenerator
...
'defaultMediaType'
...
property
...
or
...
using
...
the
...
extension
...
mappings
...
and
...
adding
...
a
...
.wadl
...
at
...
the
...
end
...
of
...
request
...
URI
...
instead
...
of
...
using
...
a
...
_wadl
...
query:
...
"http://localhost:8080/store/books/orders/fiction.wadl",
...
where
...
extensions
...
will
...
map
...
a
...
'wadl'
...
to
...
'application/vnd.sun.wadl+xml'
...
or
...
indeed
...
to
...
'application/xml'.
...
WADL
...
in
...
JSON
...
format
...
Use
...
a
...
"?_wadl&_type=json"
...
or
...
something
...
like
...
"fiction.wadl",
...
where
...
extensions
...
will
...
map
...
a
...
'wadl'
...
to
...
'application/json'
...
in
...
order
...
to
...
get
...
a
...
WADL
...
JSON
...
representations,
...
please
...
see
...
...
...
...
for
...
more
...
information.
...
Hiding
...
links
...
to
...
JAXRS
...
endpoints
...
from
...
the
...
services
...
page
...
In
...
some
...
cases
...
you
...
may
...
not
...
want
...
the
...
users
...
to
...
see
...
the
...
links
...
to
...
some
...
JAXRS
...
endpoints.
...
For
...
example,
...
if
...
you
...
have
...
an
...
AtomPullServer
...
endpoint
...
collecting
...
the
...
log
...
entries
...
for
...
a
...
number
...
of
...
application
...
endpoints,
...
you
...
may
...
not
...
want
...
to
...
see
...
AtomPullServer
...
endpoint
...
being
...
listed
...
among
...
the
...
endpoints
...
representing
...
the
...
actual
...
application
...
and
...
which
...
users
...
are
...
actually
...
interested
...
in.
...
If
...
so
...
then
...
adding
...
an
...
"org.apache.cxf.endpoint.private"
...
boolean
...
property
...
with
...
a
...
value
...
"true"
...
will
...
do
...
the
...
trick;
...
note
...
the
...
same
...
property
...
can
...
be
...
used
...
by
...
jaxws
...
endpoints.
...