Geek Answers Handbook

Documenting Jersey Vacation Api

I am looking for a way to create documentation for my Rest API created using the Jersey framework.

Are there any tools for creating such documentation? Also, what are the best methods for documenting the Rest API.

+7
java rest jersey documentation-generation
source share
2 answers

A few months ago I did a little work on this study, and my conclusion was that the most convenient structure for documenting the Jersey APIs (and many others!) Is "Swagger" - http://swagger.io/ . This is an open source project ( https://github.com/swagger-api/swagger-core ) and is very easy to use / integrate. You simply add some annotations to your REST API and generate a “website” with all the API resources, request / response messages, and even let you test directly from there. The following is an example API resource documentation:

@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{ ...

@Api... are Swagger annotations. Here you can see a live demonstration of the API documentation: http://swagger.io/swagger-ui/

There are other projects that:

  • http://enunciate.codehaus.org : this also seems like an interesting project, seems to be more in line with the classic javadocs documentation type.
+6
source share

We are working on miredot . It should work outside the box without adding (m) any additional annotations. Any feedback is appreciated.

+3
source share

More articles:


All Articles