如何正確規範寫接口文檔
阿新 • • 發佈：2018-07-16
idt param 錯誤 source href 開始 是否 重要 dfa
前言
正規的團隊合作或者是項目對接，接口文檔是非常重要的，一般接口文檔都是通過開發人員寫的。一個工整的文檔顯得是非重要。下面我將我看到的一篇接口文檔做一個總結
開始吧！！！
接口1： 查詢排重接口
| 接口詳情 | |
|---|---|
| 地址 | http://www.baidu.com （正式環境） |
| 請求方式 | GET |
| 參數 | 是否必填 | 說明 |
|---|---|---|
| idfa | 是 | 廣告標識符，只支持單個查詢 |
| source | 是 | 渠道來源，具體值在接入時再進行分配 |
| 返回結果 | 格式 | JSON |
|---|---|---|
| 狀態碼 | 10000 | success（調用成功） |
| 10001 | param error(參數錯誤) | |
| 10002 | query failed（查詢失敗） | |
| 10010 | access prohibited(訪問拒絕) |
具體返回結果舉例：
1、查詢成功
{ "state": 10000, "message": "success", "data": { "BD239708-2874-417C-8292-7E335A537FAD": 1 //已經存在 } } { "state": 10000, "message": "success", "data": {"BD239708-2874-417C-8292-7E335A537FAD": 0 //不存在 } }
- 接口調用失敗
{ "state": 10010, "message": "access prohibited", "data": [ ] }
如何正確規範寫接口文檔