?前言

大家,我是田螺。

我們做后端開發的,經常需要定義接口文檔。

最近在做接口文檔評審的時候，發現一個小伙伴定義的出參是個枚舉值，但是接口文檔沒有給出對應具體的枚舉值。其實，如何寫好接口文檔，真的很重要。今天田螺哥，給你帶來接口文檔設計的12個注意點~

1. 你的接口名稱是否清晰？

換句話說，你的接口是做什么的，是否易懂清晰？一般接口url也要求能看得出接口的作用。比如說，查詢用戶信息（queryUserInfo），就是一個不錯的接口名稱。

2. 你的接口地址是否完整

接口的地址，也叫接口的URL?地址。即別人調用你的接口，用的是什么URL?。比如/api/user/queryUserInfo?就是一個接口地址。但是，我想說的是，這還不是一個完整的接口地址。你的接口是不是HTTP調用呢？

如果是HTTP?調用的話，域名是什么呢？端口呢。一個好的http接口地址，應當是這樣的：

https//tianluo.com:15000/api/user/queryUserInfo

3.你的接口請求方式是否正確

接口請求方式通常有以下幾種：

• GET：從服務器獲取資源，可以在URL中傳遞參數，通常用于查詢數據。
• POST：向服務器提交數據，通常用于新增、修改、刪除等操作。
• PUT：向服務器更新資源，通常用于更新數據。
• DELETE：從服務器刪除資源，通常用于刪除數據。
• PATCH：向服務器局部更新資源，通常用于修改部分數據。
• HEAD：類似于GET請求，但是只返回響應頭，不返回實體內容，通常用于獲取資源的元信息。
• OPTIONS：請求服務器返回支持的請求方式等信息，通常用于客戶端與服務端協商請求方式。

你定義接口文檔的時候，需要寫清楚，你的接口請求方式是哪一個？一般情況下，我們用POST和GET?比較多。也有些公司的所有接口都用POST請求。

4.請求參數的8大要素

我們定義接口的時候,請求參數是最主要的部分之一。一份合格的接口文檔,請求參數應當包含這八大要素:

• 參數名: 參數的名字,都是駝峰命名，比如userId。
• 類型: 參數的類型,比如String、Integer等。
• 是否必填: 請求參數是不是必填的，如果要求必填的，當上游不傳這個參數的時候，應當拋參數校驗異常。
• 默認值: 如果這個參數不傳，是否有默認值，默認值是多少。
• 取值范圍: 如果是Long，Integer等數值類型的話，這個就是一個范圍值，比如1~10，如果是枚舉值的話，那就是枚舉范圍，比如ACTIVE、INACTIVE。
• 參數格式：比如你的參數是個日期的話，就需要說明參數格式，如yyyyMMdd
• 入參示例值: 提供該響應參數的示例值，以便開發人員更好地理解和使用該參數。
• 備注: 如果這個入參字段有特殊說明的話，可以在這一欄說明。如果沒有特殊說明，那只描述這個參數作用也可以。

以下就是入參的文檔樣例：

5.響應參數的7大要求

響應參數其實跟入參差不多，有7種要素：

• 參數名稱：描述該響應參數的名稱。
• 參數類型：描述該響應參數的數據類型，如String、Integer等。
• 參數格式：描述該響應參數的數據格式，如yyyy-MM-dd、HH:mm:ss等。
• 參數說明：對該響應參數的含義進行詳細的描述。
• 取值范圍：描述該響應參數的取值范圍，如整數范圍、字符串長度等。
• 是否必填：描述該響應參數是否為必填項。
• 示例值：提供該響應參數的示例值，以便開發人員更好地理解和使用該參數。

不一樣的地方是，響應參數，一般都是按照code，msg，data的格式返回的：

{
    "code": 0,
    "message": "success",
    "data": {
        "name": "Tom",
        "age": 20,
        "gender": "男"
    }
}

6. 接口錯誤碼

一份好的接口文檔，一定少不了錯誤碼列舉。一般錯誤碼定義包括三列：錯誤碼、錯誤碼信息、含義

7.接口安全

定義接口文檔時，對于一些需要保護的接口，也需要考慮接口的安全，例如權限管理、防止 SQL 注入等。

因此，接口文檔應當包含接口的安全性說明：例如接口的訪問授權方式、數據傳輸加密方式等。此外，接口文檔還應該對于敏感數據和操作進行標注，方便使用者注意隱私和安全問題。

8. 接口版本管理

在接口文檔定義時，接口版本管理是非常重要的一個方面。由于軟件項目的迭代和升級，接口可能會隨著版本的變化而發生變化。為了避免接口變化給用戶帶來不必要的困擾，需要對接口進行版本管理。

以下是一些常用的接口版本管理方法：

• 在接口文檔中明確版本號：在接口文檔中明確標識接口的版本號，例如在接口地址中添加版本號信息，如https://example.com/api/v1/user，表示該接口的版本號為v1。
• 使用語義化版本號：采用語義化版本號（Semantic Versioning）規范，即版本號格式為X.Y.Z，其中X表示主版本號、Y表示次版本號、Z表示修訂號。當進行兼容性變更時，需升級主版本號；當增加功能且不影響現有功能時，需升級次版本號；當進行bug修復或小功能改進時，需升級修訂號。
• 增量發布：在接口發生變化時，先發布新版本的接口，同時保留舊版本的接口。用戶可以根據自己的需求來選擇使用哪個版本的接口。隨著新版本的接口逐步替換舊版本的接口，最終可以將舊版本的接口廢棄。

無論采用何種方法，接口版本管理都應該得到充分的考慮。在接口版本變化時，需要及時更新接口文檔（詳細描述版本的變化、兼容性問題、版本切換方式等），以確保用戶能夠獲得最新的接口信息。

9. 維護接口文檔更新迭代

如果接口發生了變更，比如參數有哪些變更，錯誤碼變更等等，都需要維護到文檔上。同時需要登記變更的記錄。

10.明確請求頭有哪些

接口文檔，是需要寫清楚的請求頭的。接口文檔的請求頭可以看到以下的信息：

• Content-Type：指定請求體的數據格式，如application/json、application/x-www-form-urlencoded、multipart/form-data等。
• Authorization：用于身份驗證的令牌信息，如Token、Bearer等。
• Accept：指定客戶端可以接受的響應數據格式，如application/json、text/html等。
• User-Agent：指定客戶端的類型和版本信息，可以用于服務端進行針對性優化。
• Accept-Encoding：指定客戶端可以接受的數據壓縮格式，如gzip、deflate等。
• Cache-Control：指定客戶端緩存的策略，如no-cache、max-age等。
• Cookie：包含客戶端發送給服務器的cookie信息。

這是是一個接口文檔的請求頭的示例：

POST /api/user HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Accept: application/json
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.110 Safari/537.36
Accept-Encoding: gzip, deflate, br
Cache-Control: no-cache
Cookie: _ga=GA1.2.1234567890.1234567890; _gid=GA1.2.0987654321.0987654321
If-None-Match: W/"2a-3TjT7VaqgkT1nJdKjX9Cpijp2FA"
Referer: https://example.com/login
Origin: https://example.com
Content-Length: 43

{"name": "John Doe", "age": 25, "email": "john.doe@example.com"}

11 接口請求示例

接口文檔，需要提供接口的使用案例：以方便開發者理解接口的使用方法和調用流程。

12. 接口測試

一般來說，接口文檔需要完善：接口測試的方法和測試結果，以便用戶可以測試接口是否符合自己的需求，讓用戶用得放心~哈哈