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.