Question

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

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

Answer 1

几个月前我对此做了一些研究，我的结论是，记录泽西岛（以及许多其他！）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）任何额外的注释。欢迎任何反馈。

记录泽西岛休息api的

2 个答案: