Howto automate documentation of a REST API (Jersey Implementation)

Question

Hey guys,

I have written a pretty extensive REST API using Java Jersey (and JAXB). I have also written the documentation using a Wiki, but its been a totally manual process, which is very error-prone, especially when we need to make modifications, people tend to forget to update the wiki.

From looking around, most other REST API's are also manually creating their documentation. But I'm wondering if theres maybe a good solution to this.

The kind of things which need to be documented for each endpoint are:

• Service Name
• Category
• URI
• Parameter
• Parameter Types
• Response Types
• Response Type Schema (XSD)
• Sample requests and responses
• Request type (Get/Put/Post/Delete)
• Description
• Error codes which may be returned

And then of course there are some general things which are global such as

• Security
• Overview of REST
• Error handling
• Etc

These general things are fine to describe once and don't need to be automated, but for the web service methods themselves it seems highly desirable to automate it.

I've thought of maybe using annotations, and writing a small program which generates XML, and then an XSLT which should generate the actual documentation in HTML. Does it make more sense to use custom XDoclet?

Any help would be much appreciated, Alan

Answer 1

I hate to be the bearer of bad news, but if you feel the need to document the things you listed, then you probably did not create a REST interface.

REST interfaces are documented by identifying a single root URL and then by describing the media type of the representation that is returned from that URL and all the media types that can be accessed via links in that representation.

What media types are you using?

Also, put a link to RFC2616 in your docs. That should explain to any consumer how to interact with your service.

Answer 2

Hi Alan,

you might be interested in Jerseys ability to provide so called WADL description for all published resources in XML format at runtime (generated automatically from annotations). This should be containing already what you need for basic documentation. Further you might be able to add additional JavaDoc, though this requires more configuration.

Please look here: http://wikis.sun.com/display/Jersey/WADL

Regads, Achim

Answer 3

Darrel's answer is exactly right. The kind of description must not be given to clients of a REST API because it will lead the client developer to couple the implementation of the client to the current implementation of the service. This is what REST's hypermedia constraint aims to avoid.

You might still develop an API that is described that way, but you should be aware that the resulting system will not implement the REST architectural style and will therefore not have the properties (esp. evolvability) guaranteed by REST.

Your interface might still be a better solution than RPC for example. But be aware what it is that you are building.

Jan

Answer 4

Unfortunately, Darrel's answer is technically correct, but is hocus-pocus in the real world. It's based on the ideal that only some agree on and even if you were very careful about it, the chances are that for some reason outside your control, you can't conform exactly.

Even if you could, other developers that might have to use your API may not care or know the details of RESTful patterns... Remember that the point of creating the API is to make it easy for others to use it and good documentation is a must.

Achim's point about the WADL is good however. Because it exists, we should be able to create a basic tool for generating documentation of the API.

Some folks have taken this route, and an XSL stylesheet has been developed to do the transform: https://wadl.dev.java.net/