爲REST API構建在線文檔

Question

我正在構建我的第一個Rest API，它將數據序列化爲JSON和XML格式。 我想爲API客戶端提供一個索引頁面，他們可以在這裏選擇實現的端點。

我需要包含哪些信息才能使我的API最有用，以及如何組織它？

Answer 1

對於簡單的答案，這是一個非常複雜的問題。

您可能想看看現有的API框架，如Swagger規範（OpenAPI），以及像apiary.io和apiblueprint.org這樣的服務。另外，下面是以三種不同方式描述，組織和甚至設計相同REST API的示例。從現有的常見方式學習可能是一個好的開始。

• 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類型（如何編碼PARAMS和解析回覆）
• 樣品的請求/響應，包括HTTP標頭
• 類型和所有PARAMS指定格式，包括那些在URL，身體和頭部
• 一段簡短的文字說明和注意事項
• 短的代碼片段顯示流行的網絡編程語言使用的端點

還有很多基於JSON/XML的文檔框架可以解析您的API定義或模式，併爲您生成一組方便的文檔。但是文檔生成系統的選擇取決於您的項目，語言，開發環境和許多其他事情。