[解決済み] REST API のオンラインドキュメントの構造化

質問

私は、JSONとXML形式にデータをシリアライズする最初のRest APIを構築しています。 APIクライアントにインデックスページを提供し、そこで実装されたエンドポイントを選択できるようにしたいと思います。

私のAPIを最も有用にするために、どのような情報を含める必要がありますか、そして、どのようにそれを整理すべきですか？

どのように解決するのですか？

簡単な答えの割には、とても複雑な質問ですね。

のような既存のAPIフレームワークを見てみるとよいでしょう。 スワッガー 仕様書 ( OpenAPI のようなサービス)、および apiary.io と apiblueprint.org .

また、同じREST APIを3種類の方法で記述し、整理し、さらにスタイル付けした例もあります。既存の一般的な方法から学ぶには良いきっかけになるかもしれません。

• https://api.coinsecure.in/v1
• https://api.coinsecure.in/v1/originalUI
• https://api.coinsecure.in/v1/slateUI#!/Blockchain_Tools/v1_bitcoin_search_txid

一番上のレベルでは、質の高いREST APIドキュメントには、少なくとも次のようなものが必要だと思います。

• すべてのAPIエンドポイント(ベース/相対URL)のリスト
• 各エンドポイントに対応するHTTP GET/POST/...メソッドタイプ
• リクエスト/レスポンスの MIME タイプ (パラメータをエンコードする方法と、レスポンスを解析する方法)
• HTTPヘッダを含むリクエスト/レスポンスのサンプル
• URL、ボディ、ヘッダを含むすべてのパラメータの型と形式を指定します。
• 簡単なテキストの説明と重要な注意事項
• 一般的なウェブプログラミング言語でのエンドポイントの利用を示す短いコードスニペット

また、APIの定義やスキーマを解析し、あなたのために便利なドキュメントのセットを生成できる、JSON/XMLベースのドキュメントフレームワークがたくさんあります。しかし、ドキュメント生成システムの選択は、プロジェクト、言語、開発環境および他の多くの事柄に依存します。