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

全局說明

本文檔用于數據平臺所有對內，對外合作項目的API規范，之后新項目接口格式都按此規范執行

服務端采用了類 RESTFUL 的 API 風格(接口語義化)

所有的 GET 請求的 API 數據接口都采用 JSON 格式。標準的接口格式中都包含著 data 字段，業務數據都包含在這個 data 字段中，并且 data 字段恒為對象格式

常見錯誤通過HTTP狀態碼來返回錯誤，業務方約定錯誤通過 code 值返回錯誤

本API格式說明為服務端API規范，中間層轉發默認為全透明代理(完全按后端返回格式為準)

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

基本概念

tn : totalNumber => 總條數

sn : sizeNumber => 分頁閾值

cn : currentNumber => 當前頁數

pn : pageNumber => 總頁數

q : query => 查詢參數

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

code: 業務約定,0為正確,其他為錯誤

orderBy: key => 以 key 作為排序參數

需要注意的點

所有資源 ID 對當前接口返回統一命名為 id

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

接口格式規范、數據類型強統一

每一個接口返回的數據格式應該始終一致

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

每個字段返回的數據類型應該始終一致

字段類型是 數組 就恒為數組，空值時也應該為空數組，不能為空字符串或者 Null

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

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

常見的HTTP狀態碼

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

例子

GET方法通用返回定義

GET 方法請求單條數據返回的標準數據格式：

// response body 
{     
  "code": -1, // 錯誤狀態碼     
  "message": "服務器錯誤,請聯系對應RD負責人"  // 錯誤消息     
  "data": {         
    //數據 Body     
  }   
  // 數據格式強統一,不論單挑數據還是多條數據查詢,Data 都是對象. 
}  

GET 方法請求多條數據返回的標準數據格式：

// response body  
{      
  "code": 1,      // 錯誤狀態碼      
  "message": "服務器錯誤,請聯系對應RD負責人",  // 錯誤消息      
  "data": {          
    "tn": 999,                            // 多條數據必須返回          
    "cn": 1,                            // 多條數據必須返回          
    "pn": 10,                           // 多條數據必須返回          
    "sn": 100,                          // 多條數據必須返回          
    "q": "xx",                          // 非必須          
    "cacheTime": '2017-07-31 15:41:27'  // 如果做數據緩存的話,是在返回體里做這個還是 Header 頭?          
    "items": [{                  
         //單條數據 Body              
    },{ 
         //單條數據 Body           
    }             
     // ...          
    ]      
  }    // 數據格式強統一,不論單挑數據還是多條數據查詢,Data 都是對象.  
}   

POST方法通用返回定義

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

code 字段0表示插入成功,其他數字標識錯誤編號

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

data 內顯示新增字段的內建唯一標識碼,告訴前端數據插入到了哪里

{         
  "code": 1,      // 錯誤狀態碼         
  "message": "服務器錯誤,請聯系對應RD負責人"  // 錯誤消息         
  "data": {             
    id: 2 //新插入的事件的唯一標識碼         
  }     
} 

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

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

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

以上就是關于“統一API文檔格式”的介紹，大家若想了解更多相關知識，可以關注一下動力節點的Java學習資料，里面的課程內容詳細，通俗易懂，適合0基礎的小白學習，希望對大家能夠有所幫助。