接口文档规范.docx
《接口文档规范.docx》由会员分享,可在线阅读,更多相关《接口文档规范.docx(9页珍藏版)》请在冰点文库上搜索。
接口文档规范
XXX接口说明书
(版本:
V1.0)
文档编号
保密等级
作者
最后修改日期
审核人
最后审批日期
批准人
最后批准日期
修订记录
日期
版本
修订说明
修订人
1简介
1.1文档目的
接口文档是前端与后端交互密不可分的环节,接口的规范性会直接影响双方对接过程中的效率与质量。
本着快速高效开发的目的性,避免对接过程中的错误率。
1.2接口规范
(1)遵循RESTfulAPI设计风格
(2)数据格式采用json格式
(3)返回统一结构数据
例如:
结构:
data(数据)、errorCode(状态码)、msg(提示信息)
data:
{},//数据类型不一定为object类型
errorCode:
10001,
msg:
''
(4)枚举型参数应列举参数所有值及说明
例如:
gender:
性别(男:
1,女:
2)
userInfo:
{
name:
'张三',
age:
23,
gender:
1
(5)具有嵌套关系的参数应指明嵌套关系及子级数据结构
例如:
billList:
账单列表(父级)
billList:
[
id:
'001',
billName:
'测试数据',
billStauts:
1,
address:
'雁塔区'
(6)返回参数数据类型保持一致性
例如:
billList:
账单列表(有数据)
billList:
[
id:
'001',
billName:
'测试数据',
billStauts:
1,
address:
'雁塔区'
billList:
账单列表(无数据)
billList:
[]
返回的参数数据类型都为:
array
(7)下拉及选择型数据以键值对的形式返回
例如:
orderOperate:
订单操作
orderOperate:
[
label:
'待开票'
value:
1001
label:
'回款'
value:
1003
(8)“操作类型”的接口必须返回msg信息内容
(9)返回的展示型数据应具有可用性
例如:
createTime:
生成时间(建议格式)
createTime:
'2018-8-2017:
00:
00'
建议:
由于前台处理数据能力较弱,故后台返回的数据尽可能便于前台使用。
2接口定义
2.1特殊接口
2.1.1获取服务器sessionKey
接口标识:
接口地址:
.xxx/api/GetSessionKey
请求方式:
POST
请求参数:
参数名
类型
必填
示例值
默认值
描述
appType
number
是
1
1
1:
e站,2:
客户
code
string
否
wx.login返回的code
输出参数:
参数名
类型
示例值
默认值
描述
errorCode
number
100
100:
成功,-99:
失败,-10:
需要登录-20:
Session失效
msg
string
接口返回的文字消息
data
string
Api接口返回session值
返回示例值:
data:
'123456',
errorCode:
100,
msg:
''
2.2通用接口
2.2.1账单列表
接口标识:
接口地址:
.xxx/api/billList
请求方式:
POST
请求参数:
参数名
类型
必填
示例值
默认值
描述
id
number
是
订单id
sort
string
否
排序
gender
number
是
1
1
性别(男:
1,女:
2)
orderList
array
否
[...]
订单列表
orderList
orderId
string
否
订单id
orderName
string
否
订单名称
isStudent
boolean
是
false
false
是否学生(是:
true,否:
false)
返回参数:
参数名
类型
示例值
默认值
描述
data
array
[…]
返回的数据
data
id
string
用户id
gender
number
1
1
用户性别(男:
1,女:
2)
invoiceTitle
string
抬头
address
string
地址
billList
array
[...]
订单列表数据
billList
id
string
订单id
billName
string
订单名称
billStauts
number
1
1
订单状态(待开票:
1,回款:
2,核销:
3)
address
string
客户地址
userInfo
object
{}
用户信息
userInfo
name
name
用户姓名
age
number
用户年龄
gender
string
1
1
用户性别(男:
1,女:
2)
errorCode
number
状态信息
msg
string
信息提示
返回示例值:
data:
[
id:
'1',
gender:
2,
invoiceTitle:
'帝国快运',
address:
'陕西省西安市雁塔区科技路24号',
billList:
[
id:
'001',
billName:
'测试数据',
billStauts:
1,
address:
'雁塔区'
id:
'002',
billName:
'测试数据02',
billStauts:
1,
address:
'高新区'
userInfo:
{
name:
'张三',
age:
23,
gender:
1
id:
'2',
gender:
1,
invoiceTitle:
'圆通快递',
address:
'陕西省西安市雁塔区科技路24号',
billList:
[
id:
'003',
billName:
'测试数据',
billStauts:
1,
address:
'雁塔区'
id:
'004',
billName:
'测试数据02',
billStauts:
2,
address:
'高新区'
userInfo:
{
name:
'张三',
age:
23,
gender:
1
errorCode:
10001,
msg:
''