WADL

h1. Jersey and WADL

h2. Abstract
Out of the box Jersey generates basic WADL at runtime that you can obtain from your REST app via {{GET}} {{http://path.to.your/restapp/application.wadl}}. Additionally you can configure Jersey to create an extended WADL including e.g. additional {{doc}} elements or javadoc read from your resource classes: There's a custom doclet that writes your javadoc to a file so that it can be used to extend the WADL. Additionally there's the maven-wadl-plugin that allows you to create the WADL without your running REST app.

h2. Introduction

When you have your REST app up and running Jersey already generates WADL for you: simply {{GET}} the resource {{/application.wadl}} at the base URI of your REST app (e.g. for the helloworld sample {{GET}} {{http://localhost:9998/application.wadl}}). For a single resource you can request the {{OPTIONS}} to get the WADL for only this resource, e.g. for the helloworld sample invoke {{OPTIONS}} {{http://localhost:9998/helloworld}}.

The WADL that is generated by jersey uses all the information that is available from your resource classes (compiled bytecode) and the jersey configuration at runtime. This includes e.g. the base URI of your REST app, resources, sub-resources, resource methods with request and response representations and so on. The generated WADL for the helloworld sample ({{http://localhost:9998/application.wadl}}) e.g. looks like this:

{code}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<application xmlns="http://research.sun.com/wadl/2006/10">
<doc xmlns:jersey="http://jersey.dev.java.net/" jersey:generatedBy="Jersey: 0.10-ea-SNAPSHOT 08/27/2008 08:24 PM"/>
<resources base="http://localhost:9998/">
<resource path="/helloworld">
<method name="GET" id="getClichedMessage">
<response>
<representation mediaType="text/plain"/>
</response>
</method>
</resource>
</resources>
</application>
{code}

h2. Adding more information to the generated WADL
However, there's more information you might want to have included in the WADL that jersey cannot simply read from the compiled resource classes. These are some examples for such cases:
* When a resource method just returns a [{{Response}}|https://jsr311.dev.java.net/nonav/javadoc/javax/ws/rs/core/Response.html] (with different response entities/representations or content-types) jersey does not know which response representations are returned for different HTTP status codes.
* In a resource method you can set HTTP headers on the returned [{{Response}}|https://jsr311.dev.java.net/nonav/javadoc/javax/ws/rs/core/Response.html]. About these headers jersey does not know anything when it generates the WADL
* When you return some JAXB entity, you might want to have set the {{element}} attribute in the WADL representation element (including the xml namespace). This information is also not available to jersey, additionally the generated WADL must contain the {{grammars}} element including the required xsd files
* Mostly you add some javadoc to your resource classes and resources methods, you might want to have this documentation added as {{doc}} elements to the related WADL elements
* You might want to have a global {{doc}} element added to the generated application.wadl as an introduction to the whole REST app

An example for an extended version of a generated WADL you find [here|ExtendedWadlExample], this is what's generated for the [generate-wadl sample|https://jersey.dev.java.net/source/browse/jersey/trunk/jersey/samples/generate-wadl/].

To support the cases mentioned above, there are several {{WadlGenerator}} implementations provided. A {{WadlGenerator}} contributes to the generated WADL, and all configured {{WadlGenerators}} are composed as decorators. The basic {{WadlGeneratorImpl}} is the one that is used by default and reads everything from your resource classes that is available from the bytecode (as described above).

These {{WadlGenerators}} are available:
* {{WadlGeneratorApplicationDoc}}: adds one or more {{doc}} elements to the generated WADL. The {{doc}} elements are read from a specified xml file (an example can be seen [here|https://jersey.dev.java.net/source/browse/*checkout*/jersey/trunk/jersey/samples/generate-wadl/src/main/doc/application-doc.xml?content-type=text%2Fplain])
* {{WadlGeneratorGrammarsSupport}}: adds a {{grammars}} element to the generated WADL. The {{grammars}} element is read from a specified xml file (an example can be seen [here|https://jersey.dev.java.net/source/browse/*checkout*/jersey/trunk/jersey/samples/generate-wadl/src/main/doc/application-grammars.xml?content-type=text%2Fplain]). This is mostly useful together with the following {{WadlGenerator}}
* {{WadlGeneratorResourceDocSupport}}: add information that is read from a resource-doc file. A resource-doc file is created by a {{ResourceDoclet}} (a custom doclet), that reads the javadoc from your resource classes. You see this includes two-steps: at build time you generate the resource-doc file with javadoc configured with the {{ResourceDoclet}}. The generated resource-doc file is added to the classpath of the created artifact (jar/war file that will be deployed). When the WADL is beeing generated the {{WadlGeneratorResourceDocSupport}} reads the information from this file and adds it to the WADL.