WADL

Skip to end of metadata
Go to start of metadata

Jersey and WADL

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.

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:

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

An example for an extended version of a generated WADL you find here, this is what's generated for the generate-wadl sample.

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.

How to configure your webapp to provide extended WADL

This page describes what's necessary for getting an extended WADL generated within your running webapp.

How to generate extended WADL (without a webapp)

The generate-wadl sample shows how to generate (extended) WADL with maven, without the need to start the webapp. This sample also has a README you might want to look at.

Supported javadoc tags used by the ResourceDoclet/WadlGeneratorResourceDocSupport

This page describes, which javadoc tags are supported and used to extend the generated WADL.

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Mar 04, 2009

    I wonder whether or not it would be better to use annotations rather than special javadoc tags.  You could then let the jersey runtime store things like the return representations for each HTTP status.  It could collect all of this information at the same time it is collecting the other annotations.  To me that seems like it would be cleaner, and would aid the build process for new-to-jersey developers.  The expense is that the classes would grow a little, but not by very much.

    Possible?

    1. Mar 05, 2009

      Let's discuss this on the jersey users mailing list please, I'm responding on the list.

  2. Jul 30, 2012

        my project use jersey, and run okey, but i want to hide wadl url, eg: http://192.168.1.30:8080/epg/application.wadl ,  i hope this url can not to be visited[|], maybe 404 or other info,  but the service is okey, it can come true[|]?

        thanks, my email is weidagao@foxmail.com

Sign up or Log in to add a comment or watch this page.


The individuals who post here are part of the extended Oracle community and they might not be employed or in any way formally affiliated with Oracle. The opinions expressed here are their own, are not necessarily reviewed in advance by anyone but the individual authors, and neither Oracle nor any other party necessarily agrees with them.