接口文档标准规范Word文档下载推荐.docx
《接口文档标准规范Word文档下载推荐.docx》由会员分享,可在线阅读,更多相关《接口文档标准规范Word文档下载推荐.docx(9页珍藏版)》请在冰豆网上搜索。
接口文档是前端与后端交互密不可分环节,接口规范性会直接影响双方对接过程中效率和质量。
本着迅速高效开发目性,避免对接过程中错误率。
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)返回参数数据类型保持一致性
账单列表(有数据)
账单列表(无数据)
[]
返回参数数据类型都为:
array
(7)下拉及选取型数据以键值对形式返回
orderOperate:
订单操作
orderOperate:
label:
待开票'
value:
1001
},
回款'
1003
(8)“操作类型”接口必要返回msg信息内容
(9)返回展示型数据应具备可用性
createTime:
生成时间(建议格式)
createTime:
-8-2017:
00:
00'
}
建议:
由于前台解决数据能力较弱,故后台返回数据尽量便于前台使用。
2接口定义
2.1特殊接口
2.1.1获取服务器sessionKey
接口标记:
接口地址:
祈求方式:
POST
祈求参数:
参数名
类型
必填
示例值
默认值
描述
appType
number
是
1:
e站,2:
客户
code
string
否
wx.login返回code
输出参数:
errorCode
100
100:
成功,-99:
失败,-10:
需要登录-20:
Session失效
msg
接口返回文字消息
data
Api接口返回session值
返回示例值:
123456'
100,
2.2通用接口
2.2.1账单列表
id
订单id
sort
排序
gender
orderList
[...]
订单列表
orderList
orderId
orderName
订单名称
isStudent
boolean
false
与否学生(是:
true,否:
false)
返回参数:
[…]
返回数据
顾客id
顾客性别(男:
invoiceTitle
昂首
address
地址
billList
订单列表数据
billName
billStauts
订单状态(待开票:
1,回款:
2,核销:
3)
客户地址
userInfo
object
{}
顾客信息
name
顾客姓名
age
顾客年龄
状态信息
信息提示
1'
2,
invoiceTitle:
帝国快运'
陕西省西安市雁塔区科技路24号'
},
002'
测试数据02'
高新区'
],
2'
圆通快递'
003'
004'
10001,