REST APIのオンラインドキュメントの構築
データをJSONおよびXML形式にシリアル化する最初のRest APIを構築しています。実装されたエンドポイントを選択できるAPIクライアントにインデックスページを提供したいと思います。
APIを最も役立つものにするためにどのような情報を含める必要があり、どのように整理すればよいですか？
それは単純な答えのための非常に複雑な質問です。
Swagger Specification（ OpenAPI ）などの既存のAPIフレームワーク、および 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、本文、ヘッダーなど、すべてのパラメーターに指定されたタイプと形式
- テキストの簡単な説明と重要な注意事項
- 一般的なWebプログラミング言語でのエンドポイントの使用を示す短いコードスニペット
また、多くのJSON/XMLベースのドキュメントフレームワークがあり、API定義またはスキーマを解析して、便利なドキュメントセットを生成できます。ただし、ドキュメント生成システムの選択は、プロジェクト、言語、開発環境、その他多くの事項に依存します。