記錄澤西島休息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類型的文檔。

Answer 2

我們正在研究miredot 。 它應該是開箱即用的，不需要添加（m）任何額外的注釋。 歡迎任何反饋。