web-dev-qa-db-ja.com

RESTful APIを文書化するための標準メソッド

新しい内部WebサービスのRESTful APIの仕様を書いています。それほど長くなく、かなり単純ではありませんが、それでも、厳密なRESTを使用するのは初めてです（実際的な理由で不正行為とは対照的に、PUTおよびDELETE PHPの苦痛など）。RESTインターフェイスをドキュメント化するための標準的な方法やベストプラクティスがあるかどうか、チームの他のメンバーに理解してもらいたい一目で、そしてクライアントを書きたい人のために、基礎となるコードを理解せずにそうすることができるようにします。

restdocumentation
65
Samir Talwar

ロイの投稿で ここ 彼は述べています

A REST APIは、リソースの表現とアプリケーションの状態の駆動に使用されるメディアタイプの定義、または拡張リレーション名やハイパーテキスト対応マークの定義に、記述的な努力のほとんどすべてを費やす必要があります既存の標準メディアタイプのアップ。対象のURIで使用するメソッドの説明に費やした労力は、メディアタイプの処理ルールの範囲内で完全に定義する必要があります（ほとんどの場合、既存のメディアタイプで既に定義されています） 。

9
Darrel Miller

確かに、 REST APIは理想的にはHATEOASを使用し、ハイパーテキスト駆動である必要があります （メディアタイプを多用します）だけでなく、開発者が作業を進めるためのシンプルで人間に優しいドキュメントを用意することも役立ちます。

このようなドキュメントを生成するのに役立つ特定のツール：

  • Swagger
    • REST API [[ github ]を記述するためのオープンな仕様
    • 自動生成のためのツール
      • ドキュメンテーション
      • APIのコード
    • OpenAPIイニシアチブに寄付され、 2015年にOpenAPIに改名
  • Mashery
    • オープンソースプロジェクト[ github ]
    • 生成ツール
      • ドキュメンテーション
      • APIの探索インターフェイス
  • Apiary および API Blueprint
    • Markdown内のDSLでAPIの説明を書く
    • 自動生成のためのツール
      • ドキュメンテーション
      • モックサーバー
    • Ruby + mac devsに焦点を当てているようです
  • [〜＃〜] raml [〜＃〜]
    • REST API [[ github ]を記述するための仕様
  • [〜＃〜] wadl [〜＃〜]
    • XMLで発見可能なAPIドキュメントを記述するための仕様
    • いくつかの議論 WSDLとWADLの比較
  • APIgee
    • いくつかのドキュメント機能を備えた商用製品
  • scale
    • いくつかのドキュメント機能を備えた商用製品
  • miredot
    • コマーシャルREST APIドキュメントジェネレーター
    • Java固有
47
turtlemonvh

私は http://apiary.io を使用していますが、これはかなりいいです。 APIドキュメントをgithubにエクスポートすることもできます。

13
Martin Konecny

優れたReSTドキュメントは、メディアタイプとメディアタイプのみをドキュメント化することを意味します。

典型的なシナリオでは、次のようなドキュメントを作成します。

Acme Corp XML形式

リンク発見

さまざまなリソースへのリンクは、ブックマークURIでサーバーにGETまたはHEADリクエストを発行することで見つけることができるドキュメントに記載されています（通常、サーバーのルート、 http： //www.acme.org ）、およびHTTP Linkヘッダーを探します：

Link: <xxx>;rel="http://rel.acme.org/services";type=application/vnd.acme.services+xml

ここで、rel部分はリンク関係であり、xxxは関係が確立されたURIです。

リンク関係

このドキュメントでは、次の関係名を定義しています。

メディアの種類

application/vnd.acme.services+xmlは、アプリケーションが処理する可能性のあるリンクのリストを記述するxmlシリアル化を持つドキュメントです。

<links>
 <link rel="http://rel.acme.org/customers" href="http://www.acme.org/services/customers" type="application/vnd.acme.customers+xml" />
</link>

applcation/vnd.acme.customers+xmlは、顧客を説明するxmlシリアル化されたドキュメントです。

サンプル文書：

<customers>
 <customer firstname="Darth" lastname="Vador" href="http://www.acme.org/services/customers/28" />
</customer>

等...

ポイントは、開発者が定義したリンクをたどる方法を提供することです。最初にindexへのリンクを見つけて、ナビゲートできるもののリストを取得できるようにします。

そのドキュメントを発見すると、特定のUriで顧客のリストを見ることができ、それに対してGETを実行できることを発見します。

関心のある顧客が見つかった場合、/customers/customer/@hrefとGETを発行して、その顧客の表現を取得します。

そこから、メディアタイプに、より多くのリンクを使用して、ユーザーが使用できるアクションを埋め込むことができます。また、リソースでOPTIONSリクエストを発行して、リソースの削除を許可できるかどうかを確認したり、変更後にドキュメントを保存できる場合はPUTを追加したりすることもできます。

したがって、優れたドキュメントは決してありません。

  • 静的リンクを与える
  • 「このメディアタイプを使用してPOSTを発行できます。これは移動操作を意味します。」などのインタラクションを提供します。クライアントはPOST XMLドキュメントがそのように指定しているからです。

このすべてのポイントは、クライアントとサーバー間の最小限の結合を実現することです。クライアントは、リソースの表示と検出（フォームの表示と神が他に何を知っているか）を非常に賢くすることができますが、実際のワークフローが何であるかについてはまったく馬鹿です：サーバーが決定します。

6
SerialSeb

私の会社では、Webアプリケーション記述言語 [〜＃〜] wadl [〜＃〜] を使用して非常に満足しています。 Wikipedia describes it as：「HTTPベースのWebアプリケーションの機械可読な説明を提供するXMLベースのファイル形式」。生のWADLの記述、読み取り、理解が容易であり、RESTfulの概念に直接対応していることがわかりました。公式プロジェクトでは、XSDとRELAX NGスキーマ、およびJavaツール。

WADLを操作するためのツールとリソースは次のとおりです。

  • wadl_stylesheets 、WADLファイルからHTMLドキュメントを作成するためのXSLTスタイルシート
  • Restlet 、a Java RESTfulサーバーおよびクライアントを構築するためのフレームワーク、WADL拡張を含む

ヒント：XHTML名前空間を使用して、HTML要素を含めることにより、WADLドキュメントのdoc要素に、説明、概念、開始、使用のヒントなど、人間が読めるドキュメントを含めるようにしてください。それは大きな違いを生むことができます！

4
Avi Flax

最初は、リソースの静的なドキュメントを探しましたが、あまりにも多くの質問に答えなければなりませんでした。最終的に、IO/Docs（実際には fork ）を使用したLiveドキュメントページの使用に移行しました。うまく機能しています。

2
Raghu

rest-tool が便利かもしれません。

言語に依存しないアプローチに従って、RESTful APIの仕様、模擬実装、自動化された単体テストを記述します。また、クックブックも提供しますが、非常に初期の段階ですが、その内容は継続的に成長しています。

先ほど説明したサービスはすぐに使用できるため、実験にも適しています。

2
tombenke

理解/ドキュメントを作成するために、重量級のソリューションは必ずしも必要ではありません。 （すばらしい）ヘビーウェイトツールの例：IO/Docs/Apigee（すばらしいツールですが）。

すでにdocchainのセットアップ（doxygen/phpdoc/phpdoctor/custom/etc）がある小さなプロジェクトの場合、次のシェルスクリプトを使用して、生成された完全なドキュメントにページを含めるだけです。

https://Gist.github.com/4496972

デモ： http://pastie.org/565719

ソースコードでカスタムのコメントタグを使用するだけです。また、ソースコード（言語）を文書化するための良い出発点にもなります。

0
coderofsalvation