我正在寻找一种方法来为使用 Jersey 框架创建的 Rest API 生成文档。
是否有生成此类文档的工具? 此外,记录 Rest API 的最佳实践是什么。
最佳答案
几个月前我对此做了一些研究,我的结论是记录 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 类型的文档。
关于java - 记录 Jersey rest api 的,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/19160045/