RESTAPIのオンラインドキュメントの構造化

データをJSONおよびXML形式にシリアル化する最初のRestAPIを構築しています。実装されたエンドポイントを選択できるAPIクライアントにインデックスページを提供したいと思います。

APIを最も便利にするためにどのような情報を含める必要があり、どのように整理する必要がありますか？

簡単な答えを出すには、これは非常に複雑な質問です。

Swagger仕様（OpenAPI）などの既存のAPIフレームワーク、およびapiary.ioやapiblueprint.orgなどのサービスを確認することをお勧めします。

また、3つの異なる方法で説明、整理、さらにはスタイル設定された同じRESTAPIの例を次に示します。既存の一般的な方法から学ぶことはあなたにとって良いスタートかもしれません。

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

最上位レベルでは、高品質のRESTAPIドキュメントには少なくとも次のものが必要だと思います。

• すべてのAPIエンドポイントのリスト（ベース/相対URL）
• 各エンドポイントに対応するHTTPGET / POST / ...メソッドタイプ
• 要求/応答MIMEタイプ（パラメーターをエンコードして応答を解析する方法）
• HTTPヘッダーを含むサンプルの要求/応答
• URL、本文、ヘッダーを含むすべてのパラメータに指定されたタイプと形式
• 簡単なテキストの説明と重要な注意事項
• 一般的なWebプログラミング言語でのエンドポイントの使用を示す短いコードスニペット

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