正確規範寫接口文檔

正確規範寫接口文檔

---

前言

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

---

接口規範內容

• 接口名稱
• 場景說明
• 接口說明
• 請求參數
• 響應參數
• 錯誤碼

參數內容

字段名 
變量名 
是否必填 
類型 
示例值 
描述

錯誤碼內容

名稱 
描述 
原因 
解決方案

---

一.銀聯接口文檔示例 （適用於接口規範文件）

5.2.2 統一收單線下交易查詢

5.2.2.1 場景說明

收單機構可以通過該接口主動查詢訂單狀態，完成下一步的業務邏輯。需要調用查詢接口的情況:

當收單機構後臺、網絡、服務器等出現異常，收單機構系統最終未接收到支付通知;調用支付接口後，返回系統錯誤或未知交易狀態情況;調用alipay.trade.pay，返回INPROCESS的狀態;調用alipay.trade.cancel之前，需確認支付狀態。

---

5.2.2.2 接口說明

公共請求參數中的method填寫alipay.trade.query。

---

5.2.2.2.1 請求參數

參數	參數名	類型	是否必填	最大長度	描述	示例值
out_trade_no	商戶訂單號	String	否	32	訂單支付時傳入的商戶訂單號,和網聯交易號不能同時爲空。trade_no,out_trade_no如果同時存在優先取trade_no	20150320010101001
...	...	...	...	...	...	...
trade_no	網聯交易號	String	否	64	網聯交易號，和商戶訂單號不能同時爲空	2014112611001004680073956707

---

5.2.2.2.2 響應參數

參數	參數名	類型	是否必填	最大長度	描述	示例值
trade_no	網聯交易號	String	是	64	網聯交易號	2013112011001000000121536
...	...	...	...	...	...	...
out_trade_no	商戶訂單號	String	是	32	商戶訂單號	6823789339978240

TradeFundBill字段說明:

參數	參數名	類型	是否必填	最大長度	描述	示例值
fund_channel	資金渠道	String	是	32	交易使用的資金渠道	ALIPAYACCOUNT
...	...	...	...	...	...	...

---

5.2.2.3 錯誤碼

錯誤碼	錯誤描述	原因	解決方案
SYSTEMERROR	接口返回錯誤	系統超時	請不要更換商戶退款單號，請使用相同 參數再次調用 API。
NOTENOUGH	餘額不足	商戶可用退 款餘額不足	此狀態代表退款申請失敗，商戶可根據 具體的錯誤 示做相應的處理。
...	...	...	...

---

二.API開發接口文檔示例 （適用於http、https 接口）

3.1.1 查詢排重接口

3.1.1.1 場景說明

查詢信息是否已存在。

---

3.1.1.2 接口詳情

3.1.2.1 接口地址

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

---

3.1.2.2 參數

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

---

3.1.2.3 返回結果

返回結果	格式	JSON
狀態碼	10000	success（調用成功）
	...	...
	10010	access prohibited(訪問拒絕)

---

3.1.1.3 調取示例

3.1.1.3.1 查詢成功

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

---

3.1.1.3.2 接口調用失敗

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