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

user_57097 0
Viewed 54547

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?

jersey documentation rest automation java
7 Answers

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

user_156190

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

Admin1

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

user_2671960
Related