正确规范写接口文档

正确规范写接口文档

---

前言

　　正规的团队合作或者是项目对接，接口文档是非常重要的，一般接口文档都是通过开发人员写的。一个工整的文档显得是非重要。下面我总结下自己看到的优秀接口文档。

---

接口规范内容

• 接口名称
• 场景说明
• 接口说明
• 请求参数
• 响应参数
• 错误码

参数内容

字段名 
变量名 
是否必填 
类型 
示例值 
描述

错误码内容

名称 
描述 
原因 
解决方案

---

一.银联接口文档示例 （适用于接口规范文件）

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": [ 
] 
}