接口文档规范

1、xxx接口文档XXXS口说明书（版本:V1.0）文档编号保密等级作者最后修改日期审核人最后审批日期批准人最后批准日期xxx接口说明修订记录日期版本修订说明修订人IIxxx接口说明1简介1.1 文档目的接口文档是前端与后端交互密不可分的环节，接口的规范性会直接影响双方对接过程中的效率和质量。本着快速高效开发的目的性，避免对接过程中的错误率。1.2 接口规范(1)遵循RESTfulAPI设计风格(2)数据格式采用json格式(3)返回统一结构数据例如：结构：data(数据)、errorCode(状态码)、msg(提示信息)data:,数据类型不一定为object类型errorCode:10001,

2、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:返回的参数数据类

3、型都为：array(7)下拉及选择型数据以键值对的形式返回例如：orderOperate订单操作orderOperate:label:待开票value:1001,label:回款value:1003(8)操作类型”的接口必须返回msg信息内容(9)返回的展示型数据应具有可用性例如：createTime：生成时间(建议格式)createTime:2018-8-2017:00:00建议：由于前台处理数据能力较弱，故后台返回的数据尽可能便于前台使用52接口定义2.1 特殊接口2.1.1 获取服务器sessionKey接口标识:接口地址：请求方式：POST请求参数:参数名类型|必填示例值默认值描述ap

4、pTypenumber是111:e立,2:客户codestring否wx.login返回的code输出参数:参数名类型示例值默认值描述errorCodenumber100100:成功,-99:失败,-10:需要登录-20:Session失效msgstring接口返回的文字消息datastringApi接口返回session值返回示例值data:123456,errorCode:100,msg:2.2 通用接口2.2.1账单列表接口标识:接口地址：请求方式：POST请求参数:参数名类型必填示例值默认值描述idnumber是订单idsortstring否排序gendernumber是11性别（男：

5、1,女：2）orderListarray否1订单列表orderListorderIdstring否订单idorderNamestring否订单名称isStudentboolean是falsefalse是否学生（是：true,否：false）返回参数:参数名类型示例值默认值描述dataarray返回的数据dataidstring用户idgendernumber11用户性别（男：1,女：2）invoiceTitlestring抬头addressstring地址billListarray.订单列表数据billListidstring订单idbillNamestring订单名称billStautsnu

6、mber11订单状态（彳f开票：1,回款：2,核销：3）addressstring客户地址userinfoobject用户信息userinfonamename用户姓名agenumber用户年龄genderstring11用户性别（男：1,女：2）errorCodenumber状态信息msgstring信息提示返回示例值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:雁塔