正确规范写接口文档

正确规范写接口文档


前言

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


接口规范内容

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

参数内容

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

错误码内容

名称 
描述 
原因 
解决方案


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

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商户订单号String32订单支付时传入的商户订单号,和网联交易号不能同时为空。trade_no,out_trade_no如果同时存在优先取trade_no20150320010101001
.....................
trade_no网联交易号String64网联交易号,和商户订单号不能同时为空2014112611001004680073956707

5.2.2.2.2 响应参数
参数参数名类型是否必填最大长度描述示例值
trade_no网联交易号String64网联交易号2013112011001000000121536
.....................
out_trade_no商户订单号String32商户订单号6823789339978240
TradeFundBill字段说明:
参数参数名类型是否必填最大长度描述示例值
fund_channel资金渠道String32交易使用的资金渠道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
状态码10000success(调用成功)
 ......
 10010access 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": [ 

}


阅读更多
想对作者说点什么?

博主推荐

换一批

没有更多推荐了,返回首页