java - 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

几个月前我对此进行了一些研究，我的结论是记录 Jersey（以及许多其他人！）REST API 的最佳框架是“Swagger” - http://swagger.io/。它是一个开源项目（https://github.com/swagger-api/swagger-core），使用/集成非常简单。您只需向 REST API 添加一些注释，它就会生成一个包含所有 API 资源、请求/响应消息的“网站”，甚至允许直接从那里执行测试。以下是 API 资源的文档示例：

@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...注释是 Swagger 注释。您可以在此处查看 API 文档的现场演示：http: //swagger.io/swagger-ui/

还有一些其他项目，即：

• http://enunciate.codehaus.org：这看起来也是一个有趣的项目，它似乎更遵循经典的 javadocs 类型的文档。

Answer 2

我们正在研究miredot。它应该开箱即用，无需添加（m）任何额外的注释。欢迎任何反馈。