接口文档规范

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:'2018-8-20 17:00:00'
}
建议：
由于前台处理数据能力较弱，故后台返回的数据尽可能便于前台使用。

2接口定义
2.1特殊接口
2.1.1获取服务器sessionKey
接口标识：
接口地址：https:///api/GetSessionKey 请求方式：POST
请求参数：
输出参数：
返回示例值:
{
data: '123456',
errorCode:100,
msg:''
}
2.2通用接口
2.2.1账单列表
接口标识：
接口地址：https:///api/billList 请求方式：POST
请求参数：
返回参数：
返回示例值:
{
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:''
}
如有侵权请联系告知删除，感谢你们的配合！如有侵权请联系告知删除，感谢你们的配合！。