接口文档规范.doc

XXX接口说明书
(版本：V1.0)

文 档 编 号

保 密 等 级

作 者

最后修改日期

审 核 人

最后审批日期

批 准 人

最后批准日期

修订记录
日期
版本
修订说明
修订人

1 简介
1.1 文档目的
接口文档是前端与后端交互密不可分的环节，接口的规范性会直接影响双方对接过程中的效率和质量。本着快速高效开发的目的性，避免对接过程中的错误率。
1.2 接口规范
(1) 遵循RESTful API设计风格
(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: '2023-8-20 17:00:00'
}

建议：
由于前台解决数据能力较弱，故后台返回的数据尽也许便于前台使用。
2 接口定义
2.1 特殊接口
2.1.1 获取服务器sessionKey
接口标记：
接口地址：
请求方式：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 账单列表
接口标记：
接口地址：
请求方式：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: ''
}