8

Jersey フレームワークを使用して作成された Rest API のドキュメントを生成する方法を探しています。

そのようなドキュメントを生成するツールはありますか? また、Rest API を文書化するためのベスト プラクティスは何ですか。

4

2 に答える 2

6

数か月前にこれについて少し調査した結果、Jersey (および他の多くの!) REST API を文書化するための最も優れたフレームワークは "Swagger" - http://swagger.io/であるという結論に達しました。これはオープン ソース プロジェクト ( https://github.com/swagger-api/swagger-core ) であり、使用/統合が非常に簡単です。REST API にいくつかの注釈を追加するだけで、すべての API リソース、要求/応答メッセージを含む「Web サイト」が生成され、そこから直接テストを実行することもできます。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 タイプのドキュメントに沿っているようです。
于 2013-10-04T06:13:23.813 に答える
3

私たちはmiredotに取り組んでいます。追加の注釈を (m) 追加しなくても、すぐに使用できるはずです。どんなフィードバックでも大歓迎です。

于 2014-01-24T16:13:06.323 に答える