いくつかの REST サービスを実行する Rails ベースのサーバーと、ActiveResource を使用してサーバーと対話する Rails ベースの Web UI があります。同じサーバーが他のクライアント (モバイルなど) によって使用されています。REST インターフェイスのドキュメントを生成する必要があります。各サービスのサービス URL、入力/出力、およびエラー ドキュメント構造を提供する必要があります。
理想的には、既存のトラフィックに基づいてサービスを文書化するインターセプターをサーバー側で使用したいと考えています。これを行う宝石があるかどうか疑問に思っています。
Darrel と Jon は正しいです。さらに、API はそのルートで検出可能でなければならないことを付け加えておきます。読み取りおよび書き込みアクションを提示する必要があります。
http://vimeo.com/20781278で、Jon Moore の講演をご覧ください。
REST アーキテクチャ スタイルを適用する場合、インターフェイスを文書化する必要はありません。
クライアントとサーバー間の契約は、使用されるメディア タイプによって確立されます。他の追加のドキュメントが必要な場合は、RESTful ではありません。
したがって、サービスのドキュメント化について心配する代わりに、メディア タイプのドキュメント化にすべての記述的な努力を注いでください。サーバーのクライアントを実装するために必要なのは、メディアの種類に関する知識だけです。