接口文档规范

x x x 接口文档 XXX 接口说明书 (版 本 ： V1.0) 文 档 编 号 保 密 等 级 作 者 最后修改日期 审 核 人 最后审批日期 批 准 人 最后批准日期 x x x 接口说明 II 修订记录 日期 版本 修订说明 修订人 xxx 接口说明 1 1 简介 1.1 文档目的 接口文档是前端与后端交互密不可分的环节，接口的规范性会直接影响双方对接过程中的效率和质量。本着快速高效开发的目的性，避免对接过程中的错误率。 1.2 接口规范 (1) 遵循RESTfu l API 设计风格 (2) 数据格式采用json 格式 (3) 返回统一结构数据 例如： 结构：data（数据）、errorCode（状态码）、msg（提示信息） { data: {}, // 数据类型不一定为 object 类型 errorCode: 10001, msg: '' } (4) 枚举型参数应列举参数所有值及说明 例如： gender：性别（男：1，女：2） userInfo: { name: '张三', age: 23, gender: 1 } (5) 具有嵌套关系的参数应指明嵌套关系及子级数据结构 例如： billList: 账单列表(父级) xxx 接口说明 2 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 } ] xxx 接口说明 3 (8) “操作类型”的接口必须返回msg 信息内容 (9) 返回的展示型数据应具有可用性 例如： createTime：生成时间（建议格式） { createTime: '2018-8-20 17:00:00' } 建议： 由于前台处理数据能力较弱，故后台返回的数据尽可能便于前台使用。 xxx 接口说明 4 2 接口定义 2.1 特殊接口 2.1.1 获取服务器 sessionKey 接口标识： 接口地址：https://ww.xxx.com/api/GetSessionKey 请求方式：POST 请求参数： 参数名 类型 必填 示例值 默认值 描述 appTy pe nu mber 是 1 1 1:e 站,2:客户 code string 否 wx.login 返回的 code 输出参数： 参数名 类型 示例值 ...