How to automate documentation of a REST API (Jersey Implementation)

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?

Swagger is a beautiful option. It's a project on GitHub, has Maven integration and loads of other options to keep it flexible.

Integration guide: https://github.com/swagger-api/swagger-core/wiki

More Information: http://swagger.io/

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/

Although i'm not sure it will totally fit your needs, take a look at enunciate. It seems like a good documentation generator for various web-services architectures.

EDIT Enunciate is available under github umbrella

you might be interested in Jersey's 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 that requires more configuration.

Please look here: https://jersey.java.net/documentation/latest/wadl.html

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

You might find rest-tool useful. It follows language agnostic approach to write specification, mock implementation and automated unit-testing for RESTful APIs.

You can use it only for documenting your APIs, but this specification can immediately be used to quality assure the implementation of the real services.

If your services are not fully implemented yet, but for example should be used by a web frontend application, rest-tool provides instant mocking based on the service description. content schema validation (JSON schema) also can be easily added beside the documentation as well as used by the unit tests.

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.