Documenting Jersey rest api's

Question

I am looking for a way to generate documentation for my Rest API's that were created using the Jersey framework.

Are there any tools to generate such documentation? Also, what are the best practices for documenting Rest API's.

Answer 1

I did a bit of research on this some months ago and my conclusion was that the nicest framework to document Jersey (and many others!) REST APIs is "Swagger" - http://swagger.io/. It is an open source project (https://github.com/swagger-api/swagger-core) and is a very simple to use/integrate. You simply add some annotations to your REST API and it generates a "website" with all the API resources, request/response messages and even allows to perform testing directly from there. Here is an example of documentation of an API resource:

@POST
@Produces("application/json")
@Consumes({ "application/xml", "application/json"})
@ApiOperation(
    value = "Short description of resources",
    notes = "Detailed textual description of the resource...",
    responseClass = "com.example.data.resps.PostExampleResp")
@ApiErrors(value = { @ApiError(code = 404, reason = "Resources Not Found"),
    @ApiError(code = 400, reason = "Bad Request"),
    @ApiError(code = 500, reason = "Internal Error")})
public PostExampleResp postExample(
    @ApiParam(value = "Description of request message",
        required = true) PostExampleReq request) 
    throws WebApplicationException{
    ...

The @Api... annotations are the Swagger annotations. You can see a live demo of the API documentation here: http://swagger.io/swagger-ui/

There are some other projects that, namely:

• http://enunciate.codehaus.org : this also looks like an interesting project, it seems to follow more the classic javadocs type of documentation.