...

...

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 page 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:

...

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 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.

...

New: Starting from CXF 2.5.0 and 2.4.4 all WADL elements may link to top-level local declarations, see this example.

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.

...

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:

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 -async<methodNames>*javaDocs
          -generateResponseIfHeadersSet -generateResponseForMethods<methodNames>* -async<methodNames>* -xjc<xjc-arguments>* 
          -rx <library> -authentication <name:password> -validate -h -v -verbose -quiet <wadl>

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 The options are reviewed in the following table.

...

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.

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:

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:

<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:

<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>

wadl2java Maven plugin

If you need the code generated during Maven build then the following plugin can be used:

...

<wadlOptions>
	<wadlOption>
		<wadl>$\{basedir}/src/main/wadl/bookStore.wadl</wsdl>
                <extraargs>
                    <extraarg>-impl</extraarg>
                    <extraarg>-verbose</extraarg>
                </extraargs>
	</wadlOption>
</wadlOptions>

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.

...

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:

...

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

...

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:

...

@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) {...}

Support for Javadoc

In CXF 3.0.0 one can get the Javadoc documentation copied to WADL being auto-generated at runtime.

...

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.

...

• 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:

@GET
@Path("books")
@org.apache.cxf.jaxrs.model.wadlxml.XMLName("{http://books}books")
public List<Book> getBooks() {...}

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.

...

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:

...

<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.

...

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 this blog entry for more information.

...