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

全局說明

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

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

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

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

本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為正確,其他為錯誤

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

需要注意的點(diǎn)

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

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

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

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

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

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

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

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

字段類型為 對象 時，空值為null

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

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

例子

GET方法通用返回定義

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

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

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

// response body  
{      
  "code": 1,      // 錯誤狀態(tài)碼      
  "message": "服務(wù)器錯誤,請聯(lián)系對應(yīng)RD負(fù)責(zé)人",  // 錯誤消息      
  "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ù)緩存的話,是在返回體里做這個還是 Header 頭?          
    "items": [{                  
         //單條數(shù)據(jù) Body              
    },{ 
         //單條數(shù)據(jù) Body           
    }             
     // ...          
    ]      
  }    // 數(shù)據(jù)格式強(qiáng)統(tǒng)一,不論單挑數(shù)據(jù)還是多條數(shù)據(jù)查詢,Data 都是對象.  
}   

POST方法通用返回定義

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

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

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

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

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

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

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

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

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