好看的电视剧,遮天

新聞中心

這里有您想知道的互聯(lián)網(wǎng)營(yíng)銷解決方案

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

?前言

大家,我是田螺。

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

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

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

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

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

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

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

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

3.你的接口請(qǐng)求方式是否正確

接口請(qǐng)求方式通常有以下幾種：

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請(qǐng)求，但是只返回響應(yīng)頭，不返回實(shí)體內(nèi)容，通常用于獲取資源的元信息。
OPTIONS：請(qǐng)求服務(wù)器返回支持的請(qǐng)求方式等信息，通常用于客戶端與服務(wù)端協(xié)商請(qǐng)求方式。

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

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

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

參數(shù)名: 參數(shù)的名字,都是駝峰命名，比如userId。
類型: 參數(shù)的類型,比如String、Integer等。
是否必填: 請(qǐng)求參數(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è)日期的話，就需要說(shuō)明參數(shù)格式，如yyyyMMdd
入?yún)⑹纠? 提供該響應(yīng)參數(shù)的示例值，以便開(kāi)發(fā)人員更好地理解和使用該參數(shù)。
備注: 如果這個(gè)入?yún)⒆侄斡刑厥庹f(shuō)明的話，可以在這一欄說(shuō)明。如果沒(méi)有特殊說(shuō)明，那只描述這個(gè)參數(shù)作用也可以。

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

參數(shù)名	類型	是否必填	默認(rèn)值	取值范圍	參數(shù)格式	入?yún)⑹纠?/p>	備注（說(shuō)明）
userId	Long	是	0L	0~99999999L	無(wú)	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ù)說(shuō)明：對(duì)該響應(yīng)參數(shù)的含義進(jìn)行詳細(xì)的描述。
取值范圍：描述該響應(yīng)參數(shù)的取值范圍，如整數(shù)范圍、字符串長(zhǎng)度等。
是否必填：描述該響應(yīng)參數(shù)是否為必填項(xiàng)。
示例值：提供該響應(yīng)參數(shù)的示例值，以便開(kāi)發(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ò)誤	請(qǐng)求參數(shù)不合法
1002	用戶不存在	根據(jù)給定的用戶ID沒(méi)有找到對(duì)應(yīng)的用戶信息
1003	數(shù)據(jù)庫(kù)錯(cuò)誤	數(shù)據(jù)庫(kù)訪問(wèn)出錯(cuò)

7.接口安全

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

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

8. 接口版本管理

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

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

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

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

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

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

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

10.明確請(qǐng)求頭有哪些

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

Content-Type：指定請(qǐng)求體的數(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)行針對(duì)性優(yōu)化。
Accept-Encoding：指定客戶端可以接受的數(shù)據(jù)壓縮格式，如gzip、deflate等。
Cache-Control：指定客戶端緩存的策略，如no-cache、max-age等。
Cookie：包含客戶端發(fā)送給服務(wù)器的cookie信息。

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

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": "[email protected]"}

11 接口請(qǐng)求示例

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

12. 接口測(cè)試

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

當(dāng)前標(biāo)題：接口文檔設(shè)計(jì)的12個(gè)注意點(diǎn)
文章網(wǎng)址：http://m.fisionsoft.com.cn/article/cdijohg.html