2218992768
日常項目開發的過程中，接口文檔是必不可少的。後端工程師與前端工程師之間需要接口文檔來定義數據傳輸協議、系統對外暴露接口需要文檔來說明、系統之間相互調用需要文檔來記錄接口協議等等。對於一個完整的項目，接口文檔是至關重要的。那我們如何寫好一份接口文檔呢？今天就讓我們說一說接口文檔幾個重要的要素。
1、接口概述
接口概述主要說明本接口文檔涉及到的業務功能點，面向的閱讀對象以及接口文檔主要包括哪些業務的接口，可以讓讀者有一個直觀的認識。如：本文檔定義了中臺系統面向外部接入方的數據協議接口，主要包括：用戶註冊接口、同步用戶、授權認證等接口。適合閱讀的對象為接入中臺開發者或者外部合作方…。這樣的一段描述，對於閱讀者來說可以對整個接口文檔有一個大概的認識。
2、權限說明
有的接口調用需要授權認證，在這部分需要進行說明。如果接口只是基於分配的token認證，那文檔需要說明token的獲取方式。如果接口需要進行簽名認證，需要在這裡說明簽名的具體方法，如下圖：
sign參數的生成規則要具體說明，最好能示例說明，如：
這樣接入方可以驗證自己的簽名方式是否正確。
3、編碼方式
接口的請求過程中可能由於編碼導致亂碼，所以，接口必須約定編碼方式，參考以下寫法：
4、請求說明
接口文檔的請求說明中主要說明接口請求的域名以及請求的數據格式：如
5、接口列表
接口列表是接口文檔的主要內容，這部分內容需要列出所有的接口名稱、接口地址、接口的請求方式、接口的請求參數以及響應格式。在接口的請求參數中我們需要說明每個參數的含義、類型以及是否必須等屬性。對於接口響應結果，如果有業務字段，也需要進行說明。下面是一個比較完整的示例：
6、狀態碼說明
接口的響應體一般都會帶有響應的狀態碼，例如成功、失敗等。狀態碼有助於接入方進行接口調用狀態的判斷。如：
接口文檔如果能體現出以上幾個要素，那可以算是一個完整的接口文檔，對於接入方來說可以很好的閱讀理解。
阿邁達聊技術
API規範
1.接口名稱
統一使用小寫，如：order/query
2.uri
提供全路徑，如：
3.請求協議
http還是https
4.請求方法
get還是post方式
5.請求消息頭
公共的頭部參數，如版本，加密，加簽，壓縮算法，時間戳等
消息體，相關業務參數，根據實際業務說明
7.應答消息頭
公共的頭部參數，如版本，加密，加簽，壓縮算法，時間戳等
8.應答參數列表
消息體，相關業務參數，根據實際業務說明
9.返回示例
根據實際情況給出請求報文和返回報文的示例；
附錄
返回碼詳細定義，如下所示：
ksfzhaohui
開發人員有時會花幾周的時間來構建API，也許還要花一星期的時間來編寫文檔，這可能很耗時。問題是，是否有可能在20分鐘內生成API文檔？是的，這是可能的，我們現在將學習如何做。
顯然，Postman是用於測試API端點的最常用的REST客戶端，但是大多數人沒有意識到它可以用來生成格式正確的文檔。在本教程中，我們將展示一個簡單的技巧，說明如何利用Postman減輕生成文檔的壓力。
在本教程中，我不會介紹如何構建API，假設你已經有現有的API接口和對應端口和參數內容。
利用您現有的請求來生成文檔
如果您已經在Postman上測試了接口，那麼恭喜您，現在要做的就是回到請求並將它們添加到集合中。
什麼是POSTMAN集合
Postman集合使您可以隨時重用和共享的方式保存請求，它還允許您對請求進行分組，以便每個API資源都可以像一個文件夾一樣在其中保存類似的接口請求。讓我們將現有請求添加到集合中。
如何將現有請求添加到集合中。
- 在現有的請求窗口中，按住Command + S鍵
- 點擊創建收藏
- 添加您的首選名稱
- 點擊保存按鈕
完成上述步驟後，您現在有了一個集合，可以進一步添加您的請求。立即創建一個新集合，它會出現在“集合”選項卡上。
此後，您所需要做的就是將新的或現有的請求添加到集合中。Postman如何為您實現自動化？
- 標頭（可幫助您將所有標頭添加到文檔中）。
- 請求主體（發送到端點的JSON請求已複製到您的文檔中。
- 您的請求及其HTTP動詞（POST，GET，PUT，PATCH等）將自動為您添加。
您必須自己做什麼？
您可以自己為接口請求添加註釋，然後將需要的接口轉到收藏夾文件夾，並轉到任何希望添加描述的請求。
單擊編輯選項以向請求添加描述。當您單擊編輯鏈接時，將打開一個新的彈出模式，可以添加描述。
添加您的描述後，點擊保存按鈕。接下來要做的就是去任何一個要求在您的收藏夾中，併為其添加描述。剩下的一切就是在Postman服務器上發佈您的文檔。現在轉到您的收藏集，然後轉到選項菜單。
如果您在生成的文檔中發現任何錯字，則可以隨時返回到集合並進行編輯，但是不要忘記再次發佈文檔。那麼簡單的API接口文檔就自動生成了～
我是沐叔
接口文檔的好壞，對於對接人員來說還是還是很重要的，作為前端開發人員，後端給的接口很亂會讓我更亂，所以寫好一個接口文檔是非常重要的，下面就來談談寫好一個接口文檔應該注意哪些方面
接口名稱
這裡統一使用小寫 如:api/order/get
可參考跟著Github學習Restful HTTP API 設計
url提供客戶端使用的全路徑
如http://127.0.0.1:8080/api/order/get
請求協議
Http,Https
請求方式
POST,GET等
頭部(系統參數)
加密簽名,時間戳等
請求參數(業務)
業務相關的輸入參數
響應參數(業務)
輸出參數
返回示例
定義返回結果數據結構,更直觀
1.返回成功
2.返回失敗
湫音社
我做的多是項目組內部的api.一般都是一demo加上幾句簡單說明。
demo是js和ajax的
原生的很好理解。
內容是json,結構就放說明裡頭。
見過有生成工具的，說明丟註釋裡頭生成出來，也是不錯的做法，適合工作量大的項目。
