How can I generate documentation for my Jersey REST API that uses JSON JAXB binding?

Question

Now that I\'ve figured out how to use JAXB generate JSON I can request/respond with it on my server and I\'d like to figure out how I can generate useful documentation for human

Answer 1

Swagger is a good option (per @fehguy) and you should also check out enunciate and see what works best for your application...

Answer 2

Swagger uses annotations which might get you confused with other functional annotations ..

Use APIDOC for making this nice separation between functional annotations and documentation. It looks like a normal documentation above each method. ex:

/**
 * @api {get} /user/:id Request User information
 * @apiName GetUser
 * @apiGroup User
 *
 * @apiParam {Number} id Users unique ID.
 *
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 */

Answer 3

Also try enunciate, it parses the javadoc and JAX-RS annotations of your service classes to generate documentation:

http://enunciate.codehaus.org/

Here is some example documentation generated by enunciate:

https://repository.sonatype.org/nexus-restlet1x-plugin/default/docs/index.html

There is a maven plugin that works well.It also generates client libraries in various languages as well as sample xml for xml based services. It now supports swagger documentation as well.

Answer 4

Yes, this is precisely what Swagger is for. Take a look at github for details on how this integrates with JAX-RS