接口文檔設(shè)計(jì)的12個(gè)注意點(diǎn)

作者：撿田螺的小男孩 2023-04-19 08:07:24

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

?前言

大家,我是田螺。

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

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

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

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

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

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

如果是HTTP?調(diào)用的話，域名是什么呢？端口呢。一個(gè)好的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é)商請求方式。

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

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

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

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

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

參數(shù)名	類型	是否必填	默認(rèn)值	取值范圍	參數(shù)格式	入?yún)⑹纠?br>	備注（說明）
userId	Long	是	0L	0~99999999L	無	666L	用戶Id
birthDay	String	是	19900101	19900101~20231231	yyyyMMdd	19940107	用戶生日

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. 接口錯(cuò)誤碼

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

錯(cuò)誤碼	錯(cuò)誤信息	含義
1001	參數(shù)錯(cuò)誤	請求參數(shù)不合法
1002	用戶不存在	根據(jù)給定的用戶ID沒有找到對應(yīng)的用戶信息
1003	數(shù)據(jù)庫錯(cuò)誤	數(shù)據(jù)庫訪問出錯(cuò)

7.接口安全

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

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

8. 接口版本管理

在接口文檔定義時(shí)，接口版本管理是非常重要的一個(gè)方面。由于軟件項(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)行兼容性變更時(shí)，需升級主版本號；當(dāng)增加功能且不影響現(xiàn)有功能時(shí)，需升級次版本號；當(dāng)進(jìn)行bug修復(fù)或小功能改進(jìn)時(shí)，需升級修訂號。
增量發(fā)布：在接口發(fā)生變化時(shí)，先發(fā)布新版本的接口，同時(shí)保留舊版本的接口。用戶可以根據(jù)自己的需求來選擇使用哪個(gè)版本的接口。隨著新版本的接口逐步替換舊版本的接口，最終可以將舊版本的接口廢棄。

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

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

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

日期	變更描述	操作人
2023-04-16	創(chuàng)建接口文檔，定義了第一版接口文檔	撿田螺的小男孩
2023-04-18	修改接口文檔，增加了錯(cuò)誤碼，出參等	田螺哥

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信息。

這是是一個(gè)接口文檔的請求頭的示例：

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"}