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.
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:
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 (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. 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
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)
- 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). 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.
Of course you can implement your own WadlGenerator and add them to the list of used WadlGenerators.
This page describes what's necessary for getting an extended WADL generated within your running webapp.
This page describes, which javadoc tags are supported and used to extend the generated WADL.