REST API をどのように文書化しますか? リソースが何であるかのドキュメントだけでなく、実際にリクエストで送信されるデータと、レスポンスで返されるデータは何か。何かが XML の送信を期待して XML を返すことを知っているだけでは役に立ちません。またはJASN; または何でも。リクエストで送信されるデータとレスポンスで返されるデータをどのように文書化しますか?
これまでのところ、REST API とデータ要素を文書化できる Enunciate ツールが最適です。Enunciate はこれに適したタイプのツールですか? また、これを提供する他のツールを見逃すことはありませんか?
私の REST API のコンシューマは、Python、Java、.NET などの任意の言語にすることができます
私のプロジェクトで決定したアプローチは、Enunciate です。REST API ドキュメントのデファクト スタンダードのようです。
私は間違っているかもしれませんが、API を文書化するために WSDL および XML スキーマに似たものが必要なようです。Do we need WADLに関する Joe Gregorio の投稿を読むことをお勧めします。REST API にこのアプローチを使用しない理由について、適切な議論が行われています。記事全体を読みたくない場合、基本的な考えは、API のようなドキュメント (つまり WADL) では不十分であり、脆弱なインターフェイスにつながるということです。もう 1 つの良い記事は、REST には記述言語が必要ですか? です。この種の議論への良いリンクがたくさんあります。
彼の投稿は、何をすべきでないかについてのアドバイスを与えてくれますが、何をすべきかという質問には実際には答えていません。REST の重要な点は、統一されたインターフェースという考え方です。言い換えれば、GET、PUT、POST、および DELETE は、あなたがすべきだと思うことを正確に行うべきです。GET はリソースの表現を取得し、PUT は更新し、POST は作成し、DELETE は削除します。
その場合、大きな問題は、データとその意味を説明することです。いつでも XML スキーマまたは類似のものを定義するルートに進み、スキーマからドキュメントを生成できます。個人的には、機械で生成されたドキュメントがそれほど役立つとは思いません。
私の謙虚な意見では、最高のデータ形式には、例を含む広範囲で人間が読めるドキュメントがあります。これは、セマンティクスを適切に記述する方法を私が知っている唯一の方法です。この種のドキュメントを生成するためにSphinxを使用するのが好きです。
これを支援するツールを求めているのか、それともベスト プラクティスを求めているのか (またはその両方) はわかりません。
ベスト プラクティスに関しては、他のソフトウェア ドキュメントと同じことが REST ドキュメントにも当てはまります。ドリルダウンを使用して、幅の広い優れたランディング ページ (つまり、リソースの機能とその URI についての説明で論理的に編成されたリソースのリスト) を提供します。それぞれが何をするのか、例を挙げて詳しく説明しているページ。Twitter の REST API は十分に文書化されており、優れたモデルになるはずです。
私はそのドリルダウンページが大好きです。必要なすべてのパラメーターと、それぞれの説明がリストされています。サポートされているタイプを一覧表示するサイドバーがあります。関連するページや、同じタグの付いた他のページへのリンクがあります。サンプルのリクエストとレスポンスがあります。