どのようにREST APIを文書化していますか？リソースの内容だけでなく、実際に要求で送信されるデータと、応答で返されるデータとは何か。何かがXMLの送信を期待し、XMLを返すことを知るには十分有用ではありません。またはJASN。または何でも。要求で送信されるデータと応答で返されるデータをどのように文書化しますか？REST APIをどのように文書化していますか？
これまでのところ、REST APIとデータ要素を文書化できるEnunciateツールがあります。このための適切なタイプのツールを明確にしていますが、これを提供する他のツールを見逃していますか？私のREST APIの消費者は、任意の言語のPythonですることができ
、Javaや.NETなど
私は私のプロジェクトのために決めたアプローチが発音するです。 REST APIドキュメントのデファクトスタンダードと思われます。
http://enunciate.codehaus.org - Enunciateのホームページに直接リンクしています。 –
Enunciateがhttps://github.com/stoicflame/enunciate/wikiに移動 –
私はあなたにこれを手伝ってくれるツールを求めているのか、ベストプラクティス（またはその両方）が何であるかを尋ねているのかどうかはわかりません。
ベストプラクティスに関する限り、他のソフトウェアのドキュメントと同じことがRESTドキュメントに適用されます。幅広いランディングページを提供します（つまり、リソースのリストとそのURIを論理的にまとめたリスト）それぞれが何をしているのかを掘り下げて説明するドリルダウン・ページがあります。 TwitterのREST APIは非常によく文書化されており、良いモデルでなければなりません。
Sample drilldown of one resource
私は本当にドリルダウンページが大好きです。必要なすべてのパラメータと各パラメータの説明が一覧表示されます。サポートされているタイプをリストするサイドバーがあります。関連するページや同じタグを持つ他のページへのリンクがあります。サンプルリクエストとレスポンスがあります。
私は間違っているかもしれませんが、あなたのAPIを文書化するためにWSDLとXML Schemaに似たものが必要なようです。ジョー・グレゴリオの投稿をDo we need WADLに読んでみることをお勧めしますか？このアプローチをREST APIに使用しない理由については、十分な議論があります。記事全体を読んでみたくないのであれば、基本的な考え方はAPIのようなドキュメント（つまりWADL）は決して十分ではなく、脆弱なインターフェースにつながるということです。別の良い記事はDoes REST need a description languageですか？このタイプのディスカッションには、多くの良いリンクがあります。
彼の投稿はあなたが何をすべきではないかについてのアドバイスを提供していますが、実際にあなたがすべきことに関する質問には答えません。 RESTに関する大きな点は、統一されたインターフェースのアイデアです。言い換えれば、GET、PUT、POST、DELETEは、あなたがするべきことを正確に行うべきです。 GETは、リソースの表示、PUT更新、POST作成、およびDELETE削除を取得します。
大きな疑問は、あなたのデータを記述し、その意味を理解することです。 XMLスキーマなどを定義する経路を常に辿り、スキーマからドキュメントを生成することができます。個人的に、私は有用なすべての機械で生成されたドキュメントを見つけることはありません。
私の謙虚な意見では、最良のデータフォーマットには、人間が読める広範なサンプルが含まれています。これは、セマンティクスを正しく記述する方法を知っている唯一の方法です。このタイプのドキュメントを生成するのに、Sphinxの使用が好きです。
私はEnunciateの使用経験がありますが、これは素晴らしいですが、私はあなたがそれを使って生成できるクライアントが本当に好きではありません。 一方、私は最後のプロジェクトでswaggerを使用していましたが、それは私のニーズに合っているようですが、本当にあなたは試してみてください。
UPDATE 2016年3月8日：あなたが闊歩ドキュメントを構築するために発音するのに使用できるように見えます。
thisを参照してください。
FYI、Enunciate _also_ build swagger docsの現在のバージョン。 – user2163960
多分[tag：wadl] + XML Schema？ –