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 beings that are not using Java. My server code looks like this:

@POST
@Path("apath")
@Consumes(MediaType.APPLICATION_JSON)
public String postAPath(InstanceWithXmlRootElementAnnotation instanceWithXmlRootElementAnnotation) {

That's all well in good if someone is using Java. I just give them the Jar with the InstanceWithXmlRootElementAnnotation class in it and tell them to send it over (yes, there's a little more work, ignore those details).

If they're using some other language, I don't know how I'm supposed to tell them the format of their payload and what to expect from the server if it returns a InstanceWithXmlRootElementAnnotation. How can I generate documentation that explains the expected format of the JSON payload?

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

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

Answer 3

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 4

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.