RESTful APIドキュメント
もうすぐRESTful APIを設計するので、他の人がそれを使用してクライアントの実装を開始できるように、RESTful APIについて説明する必要があります。
少し調べましたが、残念ながら、WebベースのRESTfulサービスを説明する標準化された形式は見つかりませんでした。私が探しているのはJavaDocのようなものですが、どのような種類のコードからも生成する必要はありません。私はWADLのようなことについても話しているのではなく、人間が読めるドキュメントを手に入れたいと思っています。
RESTful Webベースのサービスの性質上、ドキュメントの標準化は非常に簡単です。利用可能なリソース、対応するURI、許可されたメソッド、コンテンツタイプをリストし、利用可能なアクションを説明するだけです。したがって、何か提案はありますか？
よろしくお願いします
RESTful Webベースのサービスの性質上、ドキュメントの標準化は非常に簡単です。利用可能なリソース、対応するURI、許可されたメソッド、コンテンツタイプを一覧表示し、利用可能なアクションを説明するだけです。したがって、何か提案はありますか？
これは、RESTサービスを文書化するための絶対に間違った方法です。
それらすべてを支配する1つのURI
リソースのURIを列挙しないでください。列挙すると、クライアントがそれらのURIをクライアントコードにハードコーディングするようになるためです。これにより、クライアントとサーバー間の不要な結合が作成されます。 URIは、サービスルートURIからの移動に基づいて検出する必要があります。ルートURIは、文書化する必要がある唯一のURIです。ドキュメントは、返される表現に含まれる情報とリンクの説明に重点を置く必要があります。ルートURIから返される表現から始める場合は、メディアタイプと、そのドキュメントで提供されるリンクを説明できます。
URIのエイリアス
クライアントとサーバー間の間接層を作成するには、ある種のエイリアスを使用することが重要です。リンクを定義するためにatom：link標準に従う場合、rel属性が識別子になります。ただし、リンクを定義する方法は他にもあります。たとえば、画像をHTMLに埋め込む方法などです。イメージタグには、IDとhrefを含めることができます。 Idタグは、URLにアクセスする画像を識別するために使用する必要があります。
メディアタイプはAPIを定義します
最終結果は、何らかの表現のコンテキスト内でAPIのすべてのエンドポイントを定義することです。完全なAPIは、返された表現とそれらを接続するリンクのセットによって定義されます。
あなたは尋ねるかもしれません、違いは何ですか？エンドポイントのリストを作成しないのはなぜですか？ここにいくつかの理由があります、
変更可能なURIスペース
これらのリンクはエイリアスを使用してクライアントからアクセスされるため、これにより、クライアントに影響を与えることなく、サイトのURL構造全体を完全に変更できます。これは、無限の「私の階層型URLを構造化するための最良の方法は何か」という質問のほとんどを無関係にします。 1つの方法で試すことができ、それが機能しない場合は、変更するだけで、クライアントコードを壊したり、ドキュメントを変更したりする必要はありません。
動的分布
変更できるのは、URIのパス部分だけではありません。ホストを変更することもできます。アプリが予想よりもはるかに多く使用され始めていることを想像してください。すべての画像またはビデオリソースのホストを別のサーバーを指すように簡単に変更できます。異なるホストを返すことで、単純な負荷分散を提供することもできます。 RESTful APIはステートレスであるため、どのサーバーが要求に応答するかは実際には関係ありません。この機能は、HTTPSを専用サーバーに移動する、クライアントの場所に基づいて地理的にリクエストを分散する、アプリケーションの機能を異なるサーバーに垂直に分割するなど、非常に多くのシナリオで役立ちます。
明示的なプロトコル
表現がリンクを返す可能性があるからといって、常にそうであるとは限りません。サーバーは、現在のリソースの状態に基づいて許可されているリンクのみを返すことができます。これは、サーバーリソースと対話するときに従う必要がある特定のプロトコルがある場合に非常に役立ちます。クライアントコードはプロトコルのルールを理解する必要はなく、サーバーによって利用可能にされたリンクをユーザーに提示することができます。
面白いものを自動生成することはできません
RESTサービスを文書化するためのほとんどの自動化された努力が効果的でない理由は、統一されたインターフェースが簡単なものを文書化する必要性を取り除くためです。HTTPを理解すると（RFC2616を参照）、すべてのメカニズムを理解します残されているのは、生成できない本当に興味深いドメイン固有の情報だけです。
明るい面を見てください。ドキュメントはもっと短くなるはずです。一般的なシナリオでAPIをナビゲートする方法の例を提供するために、余分な時間を費やす必要があります。
標準はありません。公開討論だけです。 InfoQに興味深い記事があります： RESTfulアプリケーションの説明 。
JAX-RS のようなものを使用する場合は、実装の実際のJavaDocを参照として使用できます。または、アノテーションスキャンを実行して自動的に生成することも、それほど難しいことではありませんが、特定の実装については知りません。