「接口文档」正确规范写接口文档

接口文档

正确规范写接口文档

前言

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

接口规范内容

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

参数内容

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

错误码内容

名称
描述
原因
解决方案

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

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

正确规范写接口文档

接口文档

正确规范写接口文档

前言

接口规范内容

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

5.2.2 统一收单线下交易查询

5.2.2.1 场景说明

5.2.2.2 接口说明

5.2.2.2.1 请求参数

5.2.2.2.2 响应参数

TradeFundBill字段说明:

5.2.2.3 错误码

二.API开发接口文档示例（适用于http、https 接口）

3.1.1 查询排重接口

3.1.1.1 场景说明

3.1.1.2 接口详情

3.1.2.1 接口地址

3.1.2.2 参数

3.1.2.3 返回结果

3.1.1.3 调取示例

3.1.1.3.1 查询成功

3.1.1.3.2 接口调用失败

相关阅读

栏目导航

推荐阅读

热门阅读

正确规范写接口文档

接口文档

正确规范写接口文档

前言

接口规范内容

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

5.2.2 统一收单线下交易查询

5.2.2.1 场景说明

5.2.2.2 接口说明

5.2.2.2.1 请求参数

5.2.2.2.2 响应参数

TradeFundBill字段说明:

5.2.2.3 错误码

二.API开发接口文档示例 （适用于http、https 接口）

3.1.1 查询排重接口

3.1.1.1 场景说明

3.1.1.2 接口详情

3.1.2.1 接口地址

3.1.2.2 参数

3.1.2.3 返回结果

3.1.1.3 调取示例

3.1.1.3.1 查询成功

3.1.1.3.2 接口调用失败

相关阅读

栏目导航

推荐阅读

热门阅读

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

二.API开发接口文档示例（适用于http、https 接口）