接口文檔規(guī)范

1、xxx接口說明PAGE xxx接口文檔XXX接口說明書(版本：V1.0)文 檔 編 號(hào)保 密 等 級(jí)作 者最后修改日期審 核 人最后審批日期批 準(zhǔn) 人最后批準(zhǔn)日期修訂記錄日期版本修訂說明修訂人簡(jiǎn)介文檔目的 接口文檔是前端與后端交互密不可分的環(huán)節(jié)，接口的規(guī)范性會(huì)直接影響雙方對(duì)接過程中的效率和質(zhì)量。本著快速高效開發(fā)的目的性，避免對(duì)接過程中的錯(cuò)誤率。接口規(guī)范(1) 遵循RESTful API設(shè)計(jì)風(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類型 errorCo

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

3、ddress: 雁塔區(qū) billList: 賬單列表（無(wú)數(shù)據(jù)） billList: 返回的參數(shù)數(shù)據(jù)類型都為：array(7) 下拉及選擇型數(shù)據(jù)以鍵值對(duì)的形式返回例如：orderOperate：訂單操作 orderOperate: label: 待開票 value: 1001, label: 回款 value: 1003 (8) “操作類型”的接口必須返回msg信息內(nèi)容(9) 返回的展示型數(shù)據(jù)應(yīng)具有可用性例如：createTime：生成時(shí)間（建議格式） createTime: 2018-8-20 17:00:00建議：由于前臺(tái)處理數(shù)據(jù)能力較弱，故后臺(tái)返回的數(shù)據(jù)盡可能便于前臺(tái)使用。接口定義特殊接口

4、獲取服務(wù)器sessionKey接口標(biāo)識(shí)：接口地址：/api/GetSessionKey請(qǐng)求方式：POST請(qǐng)求參數(shù)：參數(shù)名類型必填示例值默認(rèn)值描述appTypenumber是111:e站,2:客戶codestring否wx.login返回的code輸出參數(shù)：參數(shù)名類型示例值默認(rèn)值描述errorCodenumber100100:成功,-99:失敗,-10:需要登錄 -20:Session失效msgstring接口返回的文字消息datastringApi接口返回session值返回示例值: data: 123456, errorCode: 100, msg: 通用接口賬單列表接口標(biāo)識(shí)：接口地址：/a

5、pi/billList請(qǐng)求方式：POST請(qǐng)求參數(shù)：參數(shù)名類型必填示例值默認(rèn)值描述idnumber是訂單idsortstring否排序gendernumber是11性別（男：1，女：2）orderListarray否.訂單列表orderList orderIdstring否訂單idorderNamestring否訂單名稱isStudentboolean是falsefalse是否學(xué)生（是：true，否：false）返回參數(shù)：參數(shù)名類型示例值默認(rèn)值描述dataarray返回的數(shù)據(jù)dataidstring用戶idgendernumber11用戶性別（男：1，女：2）invoiceTitlestring

6、抬頭addressstring地址billListarray.訂單列表數(shù)據(jù)billListidstring訂單idbillNamestring訂單名稱billStautsnumber11訂單狀態(tài)（待開票：1，回款：2，核銷：3） addressstring客戶地址userInfoobject用戶信息userInfonamename用戶姓名agenumber用戶年齡genderstring11用戶性別（男：1，女：2）errorCodenumber狀態(tài)信息msgstring信息提示返回示例值: data: id: 1, gender: 2, invoiceTitle: 帝國(guó)快運(yùn), address

7、: 陜西省西安市雁塔區(qū)科技路24號(hào), billList: id: 001, billName: 測(cè)試數(shù)據(jù), billStauts: 1, address: 雁塔區(qū) , id: 002, billName: 測(cè)試數(shù)據(jù)02, billStauts: 1, address: 高新區(qū) , userInfo: name: 張三, age: 23, gender: 1 , id: 2, gender: 1, invoiceTitle: 圓通快遞, address: 陜西省西安市雁塔區(qū)科技路24號(hào), billList: id: 003, billName: 測(cè)試數(shù)據(jù), billStauts: 1, address: 雁塔區(qū) , id: 004,