接口文檔規(guī)范

1、xxx接口文檔XXXS口說明書（版本:V1.0）文檔編號保密等級作者最后修改日期審核人最后審批日期批準(zhǔn)人最后批準(zhǔn)日期xxx接口說明修訂記錄日期版本修訂說明修訂人IIxxx接口說明1簡介1.1 文檔目的接口文檔是前端與后端交互密不可分的環(huán)節(jié)，接口的規(guī)范性會直接影響雙方對接過程中的效率和質(zhì)量。本著快速高效開發(fā)的目的性，避免對接過程中的錯誤率。1.2 接口規(guī)范(1)遵循RESTfulAPI設(shè)計風(fēng)格(2)數(shù)據(jù)格式采用json格式(3)返回統(tǒng)一結(jié)構(gòu)數(shù)據(jù)例如：結(jié)構(gòu)：data(數(shù)據(jù))、errorCode(狀態(tài)碼)、msg(提示信息)data:,數(shù)據(jù)類型不一定為object類型errorCode:10001,

2、msg:(4)枚舉型參數(shù)應(yīng)列舉參數(shù)所有值及說明例如：gender：性別(男：1,女：2)userInfo:name:張三，age:23,gender:1(5)具有嵌套關(guān)系的參數(shù)應(yīng)指明嵌套關(guān)系及子級數(shù)據(jù)結(jié)構(gòu)例如：billList:賬單列表(父級)billList:id:001,billName:測試數(shù)據(jù)billStauts:1,address:雁塔區(qū)(6)返回參數(shù)數(shù)據(jù)類型保持一致性例如：billList:賬單列表(有數(shù)據(jù))billList:id:001,billName:測試數(shù)據(jù)billStauts:1,address:雁塔區(qū)billList:賬單列表(無數(shù)據(jù))billList:返回的參數(shù)數(shù)據(jù)類

3、型都為：array(7)下拉及選擇型數(shù)據(jù)以鍵值對的形式返回例如：orderOperate訂單操作orderOperate:label:待開票value:1001,label:回款value:1003(8)操作類型”的接口必須返回msg信息內(nèi)容(9)返回的展示型數(shù)據(jù)應(yīng)具有可用性例如：createTime：生成時間(建議格式)createTime:2018-8-2017:00:00建議：由于前臺處理數(shù)據(jù)能力較弱，故后臺返回的數(shù)據(jù)盡可能便于前臺使用52接口定義2.1 特殊接口2.1.1 獲取服務(wù)器sessionKey接口標(biāo)識:接口地址：請求方式：POST請求參數(shù):參數(shù)名類型|必填示例值默認值描述ap

4、pTypenumber是111:e立,2:客戶codestring否wx.login返回的code輸出參數(shù):參數(shù)名類型示例值默認值描述errorCodenumber100100:成功,-99:失敗,-10:需要登錄-20:Session失效msgstring接口返回的文字消息datastringApi接口返回session值返回示例值data:123456,errorCode:100,msg:2.2 通用接口2.2.1賬單列表接口標(biāo)識:接口地址：請求方式：POST請求參數(shù):參數(shù)名類型必填示例值默認值描述idnumber是訂單idsortstring否排序gendernumber是11性別（男：

5、1,女：2）orderListarray否1訂單列表orderListorderIdstring否訂單idorderNamestring否訂單名稱isStudentboolean是falsefalse是否學(xué)生（是：true,否：false）返回參數(shù):參數(shù)名類型示例值默認值描述dataarray返回的數(shù)據(jù)dataidstring用戶idgendernumber11用戶性別（男：1,女：2）invoiceTitlestring抬頭addressstring地址billListarray.訂單列表數(shù)據(jù)billListidstring訂單idbillNamestring訂單名稱billStautsnu

6、mber11訂單狀態(tài)（彳f開票：1,回款：2,核銷：3）addressstring客戶地址userinfoobject用戶信息userinfonamename用戶姓名agenumber用戶年齡genderstring11用戶性別（男：1,女：2）errorCodenumber狀態(tài)信息msgstring信息提示返回示例值data:id:1,gender:2,invoiceTitle:帝國快運,address:陜西省西安市雁塔區(qū)科技路24號，billList:id:001,billName:測試數(shù)據(jù),billStauts:1,address:雁塔區(qū),id:002,billName:測試數(shù)據(jù)02,billStauts:1,address:高新區(qū),userInfo:name:張三,age:23,gender:1,id:2,gender:1,invoiceTitle:圓通快遞,address:陜西省西安市雁塔區(qū)科技路24號，billList:id:003,billName:測試數(shù)據(jù),billStauts:1,address:雁塔