2016 年 3 月の更新
これが回答されてからしばらく経ち、Rest API を文書化するためのツールがたくさん登場しました。現在、 Swagger 2.0を評価しており、Open Api イニシアチブ、RAML、およびAPI ブループリントに対応しています。
WebAPI プロジェクトには、Swagger (Open API) 形式のドキュメントを自動作成するツールSwashbuckleがあります。
REST サービスを文書化するための形式:
REST サービスの記述を構造化し、標準化するいくつかの試みがあります。
上記の 2 つのアプローチのどちらもあまり広く採用されていないと言っても過言ではありませんが、WADL は見栄えの良い簡潔な形式のように見えます。ここの apigee github サイトには、いくつかの有名な API の WADL の例がたくさんあります。
適切なドキュメント形式を見つけようとするとき、私は他の人からの「インスピレーション」を探す傾向があります.... Apigee はこの分野で多くの調査を行い、これを API の 1 つのドキュメントとしてここに置くか、Facebook を見てください。ソーシャルグラフAPIはこちら.
例は、ここでのアドバイスとほぼ一致しています
ドキュメントを自動化する方法:
.NET の使用: WebApi の「ヘルプ」ページを自動生成する良い例がここにあります。この例の論理的な拡張は、WADL 形式のバージョンも出力することです...
Java の使用: Jerseyは、Java コミュニティーで WADL を自動的に生成するために使用されるツールです。
他の開発者と共有するもの:
Javascript 担当者は、Facebook や apigee のようなマニュアルを必要とする可能性が高いでしょう。リソース、URL、応答コードなどの開発例を提供します。ここで最も重要なことは、JSON を主要なコンテンツ タイプとしてサポートすることです。これは、彼/彼女が消費して操作するのが最も簡単です。
あなたのJava担当者もマニュアルを必要としますが、理論的には、送信/消費するリソースのXML表現のXSDの例を提供することもできます（リクエストを「Content-Type: appplication/xml」として行うと仮定します）。これは、プロキシ クラスなどを構築するのに役立つ場合があります。JSON から Java および .NET へのコンバーターはオンラインで入手できます。マニュアルのサンプル リソースがあれば、これらのタイプのサービスのいずれかを使用してプロキシをすばやく作成できるはずです。JSONからJavaクラスを生成しますか? .
自動検出、自動プロキシ生成などが絶対に必要な場合は、 REST と SOAP (WSDL を使用) エンドポイントの両方を選択する必要がある場合があります。関連する質問は、 ReST Proxy Object Generatorです。