Add method comment with Jersey

Question

We've been using Jersey for our webservice and it's been great and straightforward. Is there a way to add a small description comment within a method definition (maybe using an annotation like @Description):

@GET
@Path("/schema/classes/")
@Produces( { APPLICATION_RDF, TEXT_N3, APPLICATION_JSON })
@Description("Lists all ontology classes")
public Response getClasses() throws JobOntoException {
  ...
}

And in the WADL that would give something like:

<application>
 <doc jersey:generatedBy="Jersey: 1.1.5 01/20/2010 03:55 PM"/>
  <resources base="http://localhost:9998/">
   <resource path="/jobonto">
    <resource path="/schema/classes/">
     <method name="GET" id="getClasses">
      **<description>"Lists all ontology classes"</description>**
      <response> 
       <representation mediaType="application/rdf+xml"/>
       <representation mediaType="text/rdf+n3"/>
       <representation mediaType="application/json"/>
      </response>
     </method>
    </resource>
    ...

Thanks, Renaud

Answer 1

You should try extending the WadlGeneratorConfig.

• Sample project

Answer 2

Here is an even better idea. Put the description in the representation that you use to link to this resource.

What media type are you using for the representation at the root of your service? Xhtml can be very useful for this because it is easy to parse, has existing support for links and renders nicely in a browser.

Answer 3

Renaud,

are you using the WADL to provide a service description to the client developer?

If so, please not that this is not RESTful as it violates the hypermedia constraint. WADL expresses information that a client developer must not rely on. WADL essentially contains information about available transitions and the hypermedia constraint requires such information to be discovered at runtime, not to be known at design time.

Thus, using WADL ad runtime in the sense of a form is fine[1] because you can change the WADL without breaking any clients.

[1] Though the style is debatable - personally, I would rather design domain specific media types

Jan