web-dev-qa-db-ja.com

REST API（ジャージー実装）のドキュメントを自動化する方法

REST Jersey（およびJAXB）を使用して、非常に広範なJava AP​​Iを作成しました。また、Wikiを使用してドキュメントを作成しましたが、完全に手動のプロセスであり、特に修正が必要な場合は、Wikiの更新を忘れがちです。

見回すと、他のほとんどのREST AP​​Iも手動でドキュメントを作成しています。しかし、これにはおそらく良い解決策があるのだろうかと思っています。

各エンドポイントについて文書化する必要がある種類は次のとおりです。

  • サービス名
  • カテゴリー
  • URI
  • パラメータ
  • パラメータの種類
  • 応答タイプ
  • 応答タイプスキーマ（XSD）
  • サンプルのリクエストとレスポンス
  • リクエストの種類（取得/挿入/投稿/削除）
  • 説明
  • 返される可能性のあるエラーコード

そしてもちろん、グローバルないくつかの一般的なものがあります

  • セキュリティ
  • RESTの概要
  • エラー処理
  • 等

これらの一般的なことは一度説明すれば問題なく、自動化する必要はありませんが、Webサービスメソッド自体にとっては、自動化することが非常に望ましいと思われます。

注釈を使用して、XMLを生成する小さなプログラムを作成し、次にHTMLで実際のドキュメントを生成するXSLTを作成することを考えました。カスタムXDocletを使用するほうが理にかなっていますか？

javarestdocumentationautomationjersey
62
Alan Mc Kernan

Swagger は美しいオプションです。 GitHubのプロジェクトであり、Mavenの統合と、柔軟性を維持するためのその他のオプションがあります。

統合ガイド： https://github.com/swagger-api/swagger-core/wiki

詳細： http://swagger.io/

enter image description here

41
Webnet

残念なことに、Darrelの答えは技術的には正しいのですが、現実の世界では大物です。一部の人だけが同意するという理想に基づいており、あなたがそれについて非常に注意を払っていたとしても、何らかの理由であなたがコントロールできない場合、あなたは正確に従うことができない可能性があります。

APIを使用しなければならない可能性のある他の開発者は、できたとしても、RESTfulパターンの詳細を気にかけたり、知ったりすることはありません...する必要があります。

しかし、WADLについてのAchimの主張は良いことです。存在するため、APIのドキュメントを生成するための基本的なツールを作成できるはずです。

一部の人々はこのルートを採用しており、変換を行うためにXSLスタイルシートが開発されています。 https://wadl.dev.Java.net/

21
Brill Pappin

それがあなたのニーズに完全に適合するかどうかはわかりませんが、 enunciate を見てください。さまざまなWebサービスアーキテクチャに適したドキュメントジェネレータのようです。

[〜＃〜] edit [〜＃〜]Engitiateはgithubの傘の下で利用できます

16
Riduidel

実行時にXML形式で公開されたすべてのリソースの説明[〜＃〜] wadl [〜＃〜]を提供するJerseyの機能に興味があるかもしれません。 （注釈から自動的に生成されます）。これには、基本的なドキュメントに必要なものがすでに含まれているはずです。さらに、追加のJavaDocを追加できる場合がありますが、追加の構成が必要になります。

こちらをご覧ください： https://jersey.Java.net/documentation/latest/wadl.html

8
user276718

ダレルの答えは正確です。クライアントの開発者がクライアントの実装をサービスの現在の実装に結合するようになるため、REST APIのクライアントに種類の説明を与えてはいけません。これがRESTのハイパーメディアです制約は回避することを目的としています。

そのように記述されたAPIを開発することはできますが、結果のシステムはRESTアーキテクチャスタイルを実装しないため、プロパティ（特に進化可能性）が保証されないことに注意してくださいRESTによって。

たとえば、RPCよりもインターフェイスが優れたソリューションである可能性があります。しかし、あなたが構築していることは何であるかに注意してください。

ヤン

3
Jan Algermissen

rest-tool が便利かもしれません。言語に依存しないアプローチに従って、RESTful APIの仕様、模擬実装、自動化された単体テストを記述します。

APIの文書化にのみ使用できますが、この仕様は、実際のサービスの実装の品質を保証するためにすぐに使用できます。

サービスがまだ完全に実装されていないが、たとえばWebフロントエンドアプリケーションで使用する必要がある場合、 rest-tool はサービスの説明に基づいてインスタントモックを提供します。コンテンツスキーマ検証（JSONスキーマ）は、ドキュメントの横に簡単に追加でき、単体テストでも使用できます。

0
tombenke