java - 记录 Jersey rest api 的

Question

我正在寻找一种方法来为使用 Jersey 框架创建的 Rest API 生成文档。

是否有生成此类文档的工具？此外，记录 Rest API 的最佳实践是什么。

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 类型的文档。