?前言

大家,我是田螺。

我們做后端開發(fā)的,經(jīng)常需要定義接口文檔。

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

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

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

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

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

如果是HTTP?調(diào)用的話，域名是什么呢？端口呢。一個好的http接口地址，應(yīng)當(dāng)是這樣的：

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

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

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

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

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

4.請求參數(shù)的8大要素

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

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

以下就是入?yún)⒌奈臋n樣例：

5.響應(yīng)參數(shù)的7大要求

響應(yīng)參數(shù)其實(shí)跟入?yún)⒉畈欢?，?種要素：

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

不一樣的地方是，響應(yīng)參數(shù)，一般都是按照code，msg，data的格式返回的：

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

6. 接口錯誤碼

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

7.接口安全

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

因此，接口文檔應(yīng)當(dāng)包含接口的安全性說明：例如接口的訪問授權(quán)方式、數(shù)據(jù)傳輸加密方式等。此外，接口文檔還應(yīng)該對于敏感數(shù)據(jù)和操作進(jìn)行標(biāo)注，方便使用者注意隱私和安全問題。

8. 接口版本管理

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

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

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

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

9. 維護(hù)接口文檔更新迭代

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

10.明確請求頭有哪些

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

• Content-Type：指定請求體的數(shù)據(jù)格式，如application/json、application/x-www-form-urlencoded、multipart/form-data等。
• Authorization：用于身份驗(yàn)證的令牌信息，如Token、Bearer等。
• Accept：指定客戶端可以接受的響應(yīng)數(shù)據(jù)格式，如application/json、text/html等。
• User-Agent：指定客戶端的類型和版本信息，可以用于服務(wù)端進(jìn)行針對性優(yōu)化。
• Accept-Encoding：指定客戶端可以接受的數(shù)據(jù)壓縮格式，如gzip、deflate等。
• Cache-Control：指定客戶端緩存的策略，如no-cache、max-age等。
• Cookie：包含客戶端發(fā)送給服務(wù)器的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 接口請求示例

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

12. 接口測試

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