如何正確規範寫接口文檔

前言

　　正規的團隊合做或者是項目對接，接口文檔是很是重要的，通常接口文檔都是經過開發人員寫的。一個工整的文檔顯得是非重要。下面我將我看到的一篇接口文檔作一個總結

開始吧！！！

接口1： 查詢排重接口

接口詳情
地址	http://www.baidu.com （正式環境）
請求方式	GET

 

參數	是否必填	說明
idfa	是	廣告標識符，只支持單個查詢
source	是	渠道來源，具體值在接入時再進行分配

---

 

返回結果	格式	JSON
狀態碼	10000	success（調用成功）
	10001	param error(參數錯誤)
	10002	query failed（查詢失敗）
	10010	access prohibited(訪問拒絕)

具體返回結果舉例：

一、查詢成功

{
  "state": 10000,
  "message": "success",
  "data": {
    "BD239708-2874-417C-8292-7E335A537FAD": 1 //已經存在
  }
}

{
  "state": 10000,
  "message": "success",
  "data": {
    "BD239708-2874-417C-8292-7E335A537FAD": 0 //不存在
  }
}

1. 接口調用失敗

{
  "state": 10010,
  "message": "access prohibited",
  "data": [

  ]
}