接口文档标准规范.doc

PAGE PAGE 1 - 接口文档标准规范 X,X接口说明书 (版本:V1。0) 文档编号 保密等级 作 者 最后修改日期 审 核 人 最后审批日期 批准人 最后批准日期 修订记录 日期 版本 修订说明 修订人 接口文档标准规范 接口文档标准规范 1 简介 1.1 文档目的 ,接口文档是前端与后端交互密不可分的环节,接口的规范性会直接影响双方对 接过程中的效率和质量。本着快速高效开发的目的性，避免对接过程中的错误率。 1.2 接口规范 (,)遵循REST,,lAP，设计风格 (,)数据格式采用json格式 (,)返回统一结构数据 例如: da,a(数据)、,r,orCode(状态码)、msg(提示信息) 结构: { d,,a:,,， ,,数据类型不一定为object类型 errorC,de:1000,， m,g: , (4)枚举型参数应列举参数所有值及说明 例如: gender:性别(男:1,女:2) u,,,In,o:{ name:’张三’， ,ge:,,, g,nder:1 , (5)具有嵌套关系的参数应指明嵌套关系及子级数据结构 例如: billLi,,:账单列表(父级) b,ll,ist:, { id:’00,’, b,llName:测试数据’， 接口文档标准规范 bill,,,,ts:1， address:雁塔区’ , , (6)返回参数数据类型保持一致性 例如: bi,,Lis,:账单列表(有数据) billLi,,:, { ,d:’0,1， ,illName:测试数据,， billStaut,:,， ,,dre,s:’雁塔区 } , bi,lList:账单列表(无数据) bil,,i,t:[, 返回的参数数据类型都为:a,ray (7)下拉及选择型数据以键值对的形式返回 例如: o,,e,Operate:订单操作 or,,rO,erate:[ { label:,待开票, va,ue:1001 ,, , la,el:’回款’ ,al,,:1003 } , (8)“操作类型”的接口必须返回msg信息内容 (9)返回的展示型数据应具有可用性 例如: crea,eT,m,:生成时间(建议格式) { cr,a,eTime:’2,18-8,20 ,7:0,:,,’ } 接口文档标准规范 建议: 由于前台处理数据能力较弱，故后台返回的数据尽可能便于前台使用., 2 接口定义 2.1 特殊接口 2.1.1 获取服务器se,si,n,,y 接口标识: 接口地址:(x,x。;om,,p,/GetSes,ionKe, 请求方式:POST 请求参数: 参数名 类型 必填 示例值 默认描述 值 ,ppTy,e ,um,er 是 1 1 1:e站，2:客户 c,d, str,ng 否 wx(,ogin返回的code 输出参数: 参数名 类型 示例值 默认描述 值 error,ode num,er ,,, 10,:成功，-9,:失败，,,,: 需要登录-20:Ses,,,,失效 ,,g str,n, 接口返回的文字消息 d,ta string ,,,接口返回,e,s,on值 返回示例值: , ,ata:’,,3,56,， ,,rorCode:100, ms,:’ } 接口文档标准规范 2.2 通用接口 2.2.1 账单列表 接口标识: 接口地址:(xx,(com/a,,,billList 请求方式:P,,T 请求参数: 参数名 类型 必填 示例值 默认描述 值 ,d num,er 是 订单id so,t stri,g 否 排序 gender numbe, 是 , 1 性别(男:,，女:2) ,,,erL,st array 否 ,。.., 订单列表 orderLisorde,Id string 否 订单,d , ,rd,str,ng 否 订单名称 rName isS,udent bo,lean 是 fals, f,是否学生(是:tr, lse,，否:f,l,e) 返回参数: 参数名 类型 示例值 默认描述 值 arra, [?, 返回的数据 data d,i, str,ng 用户,d ta gen,er number 1 , 用户性别(男:,, 女:2) ,,voic,st,ing 抬头 Title addr,s, string 地址 billL,st ar,ay ,。(。, 订单列表数据 b,id strin, 订单i, llLi bi,l,,tring 订单名称 ,t a,e billS,n