相信大家對(duì)API文檔都不陌生，但是有很多朋友對(duì)API文檔格式規(guī)范不是很清楚，下面小編就來給大家詳細(xì)介紹一下。

全局說明

本文檔用于數(shù)據(jù)平臺(tái)所有對(duì)內(nèi)，對(duì)外合作項(xiàng)目的API規(guī)范，之后新項(xiàng)目接口格式都按此規(guī)范執(zhí)行

服務(wù)端采用了類 RESTFUL 的 API 風(fēng)格(接口語義化)

所有的 GET 請(qǐng)求的 API 數(shù)據(jù)接口都采用 JSON 格式。標(biāo)準(zhǔn)的接口格式中都包含著 data 字段，業(yè)務(wù)數(shù)據(jù)都包含在這個(gè) data 字段中，并且 data 字段恒為對(duì)象格式

常見錯(cuò)誤通過HTTP狀態(tài)碼來返回錯(cuò)誤，業(yè)務(wù)方約定錯(cuò)誤通過 code 值返回錯(cuò)誤

本API格式說明為服務(wù)端API規(guī)范，中間層轉(zhuǎn)發(fā)默認(rèn)為全透明代理(完全按后端返回格式為準(zhǔn))

與前端合作的所有 http(s) 接口需要記錄在 swagger接口管理工具中

基本概念

tn : totalNumber => 總條數(shù)

sn : sizeNumber => 分頁閾值

cn : currentNumber => 當(dāng)前頁數(shù)

pn : pageNumber => 總頁數(shù)

q : query => 查詢參數(shù)

asc: 1/0 => 升序/降序

code: 業(yè)務(wù)約定,0為正確,其他為錯(cuò)誤

orderBy: key => 以 key 作為排序參數(shù)

需要注意的點(diǎn)

所有資源 ID 對(duì)當(dāng)前接口返回統(tǒng)一命名為 id

數(shù)據(jù)庫(kù)操作 下劃線 連接所有對(duì)外字段，全部改為小駝峰

接口格式規(guī)范、數(shù)據(jù)類型強(qiáng)統(tǒng)一

每一個(gè)接口返回的數(shù)據(jù)格式應(yīng)該始終一致

同一個(gè)接口有 data 字段，不管任何情況都應(yīng)該返回 data 字段

每個(gè)字段返回的數(shù)據(jù)類型應(yīng)該始終一致

字段類型是 數(shù)組 就恒為數(shù)組，空值時(shí)也應(yīng)該為空數(shù)組，不能為空字符串或者 Null

字段類型為 字符串 就恒為字符串，空值為""

字段類型為 對(duì)象 時(shí)，空值為null

常見的HTTP狀態(tài)碼

200 ok  - 成功返回狀態(tài)，對(duì)應(yīng)，GET,PUT,PATCH,DELETE. 
201 created  - 成功創(chuàng)建。     
301 move permanently -永久重定向
302 move temporaily  -臨時(shí)重定向
304 not modified   - HTTP緩存有效。     
400 bad request   - 請(qǐng)求格式錯(cuò)誤。     
401 unauthorized   - 未授權(quán)。     
403 forbidden   - 鑒權(quán)成功，但是該用戶沒有權(quán)限。     
404 not found - 請(qǐng)求的資源不存在     
405 method not allowed - 該http方法不被允許。     
410 gone - 這個(gè)url對(duì)應(yīng)的資源現(xiàn)在不可用。     
415 unsupported media type - 請(qǐng)求類型錯(cuò)誤。     
422 unprocessable entity - 校驗(yàn)錯(cuò)誤時(shí)用。     
429 too many request  -請(qǐng)求過多。
500 interal server error  -內(nèi)部服務(wù)錯(cuò)誤
501 not implemented -未實(shí)現(xiàn)
502 bad gateway -網(wǎng)關(guān)報(bào)錯(cuò)
503 service unavailable -服務(wù)不可用
504 gateway time-out -網(wǎng)關(guān)超時(shí)

例子

GET方法通用返回定義

GET 方法請(qǐng)求單條數(shù)據(jù)返回的標(biāo)準(zhǔn)數(shù)據(jù)格式：

// response body 
{     
  "code": -1, // 錯(cuò)誤狀態(tài)碼     
  "message": "服務(wù)器錯(cuò)誤,請(qǐng)聯(lián)系對(duì)應(yīng)RD負(fù)責(zé)人"  // 錯(cuò)誤消息     
  "data": {         
    //數(shù)據(jù) Body     
  }   
  // 數(shù)據(jù)格式強(qiáng)統(tǒng)一,不論單挑數(shù)據(jù)還是多條數(shù)據(jù)查詢,Data 都是對(duì)象. 
}  

GET 方法請(qǐng)求多條數(shù)據(jù)返回的標(biāo)準(zhǔn)數(shù)據(jù)格式：

// response body  
{      
  "code": 1,      // 錯(cuò)誤狀態(tài)碼      
  "message": "服務(wù)器錯(cuò)誤,請(qǐng)聯(lián)系對(duì)應(yīng)RD負(fù)責(zé)人",  // 錯(cuò)誤消息      
  "data": {          
    "tn": 999,                            // 多條數(shù)據(jù)必須返回          
    "cn": 1,                            // 多條數(shù)據(jù)必須返回          
    "pn": 10,                           // 多條數(shù)據(jù)必須返回          
    "sn": 100,                          // 多條數(shù)據(jù)必須返回          
    "q": "xx",                          // 非必須          
    "cacheTime": '2017-07-31 15:41:27'  // 如果做數(shù)據(jù)緩存的話,是在返回體里做這個(gè)還是 Header 頭?          
    "items": [{                  
         //單條數(shù)據(jù) Body              
    },{ 
         //單條數(shù)據(jù) Body           
    }             
     // ...          
    ]      
  }    // 數(shù)據(jù)格式強(qiáng)統(tǒng)一,不論單挑數(shù)據(jù)還是多條數(shù)據(jù)查詢,Data 都是對(duì)象.  
}   

POST方法通用返回定義

POST 方法操作成功后，返回三個(gè)字段。

code 字段0表示插入成功,其他數(shù)字標(biāo)識(shí)錯(cuò)誤編號(hào)

message 字段表示代碼運(yùn)行后顯示的消息,如:插入成功 插入失敗,已有相關(guān)名稱

data 內(nèi)顯示新增字段的內(nèi)建唯一標(biāo)識(shí)碼,告訴前端數(shù)據(jù)插入到了哪里

{         
  "code": 1,      // 錯(cuò)誤狀態(tài)碼         
  "message": "服務(wù)器錯(cuò)誤,請(qǐng)聯(lián)系對(duì)應(yīng)RD負(fù)責(zé)人"  // 錯(cuò)誤消息         
  "data": {             
    id: 2 //新插入的事件的唯一標(biāo)識(shí)碼         
  }     
} 

PUT/DELETE/PATCH/OPTION方法通用返回定義

這四種方法操作成功后,返回兩個(gè)字段

{         
"code": 0, // 0 表示操作成功, 其它數(shù)字表示錯(cuò)誤編號(hào)         
"message": "數(shù)據(jù)更新成功!", 
"data": {}     
} 

以上就是關(guān)于“統(tǒng)一API文檔格式”的介紹，大家若想了解更多相關(guān)知識(shí)，可以關(guān)注一下動(dòng)力節(jié)點(diǎn)的Java學(xué)習(xí)資料，里面的課程內(nèi)容詳細(xì)，通俗易懂，適合0基礎(chǔ)的小白學(xué)習(xí)，希望對(duì)大家能夠有所幫助。