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 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.
 */