8

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.

emgsilva
  • 3,047
  • 1
  • 17
  • 16
Erik Sapir
  • 23,209
  • 28
  • 81
  • 141

2 Answers2

6

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.
technophobia
  • 2,644
  • 1
  • 20
  • 29
emgsilva
  • 3,047
  • 1
  • 17
  • 16
  • 1
    I am not sure how i should integrate swagger with my application. I am using a Tomcat server with jersey rest api's - what i should do in order to create the documentation files? – Erik Sapir Oct 05 '13 at 14:07
  • The best way is to follow the official tutorial for Java/JAX-RS(jersey): https://github.com/wordnik/swagger-core/wiki/Java-JAXRS-Quickstart, it is very good. Follow it to the line and you should get it working. Remember, it will not "generate" documentation (like Javadocs) it creates the documentation "on the fly" based on the annotations in your code (deployed web services). In the project Github there are also a lot of details/documentation/issues-reponses that can help. Furthermore the developers are extremely responsive on help solving any specific issues. – emgsilva Oct 05 '13 at 14:15
  • 3
    Swagger works on a very intrusive basis: It taps into your web-service and it needs to run in the same container. I've tried to decouple this by generating the JSON API-spec and running it separately on a Swagger-UI, but this is far from trivial and very poorly documented. – Pepster Sep 12 '14 at 15:05
3

We're working on miredot. It should work out-of-the box without adding (m)any additional annotations. Any feedback is welcome.

bertvh
  • 821
  • 1
  • 7
  • 17