Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 8 years ago.
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?
