分享介面設計文件的12個注意點

前言

我們做後端開發的,常常需要定義介面文件。

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

• 大眾號： 撿田螺的小男孩 （有田螺精心原創的面試PDF）
• github地址，感謝每顆star：github

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請求。

最主要的部分之一 。一份合格的介面文件,請求參數應包含這八大要素:

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

以下就是入參的文件範例：

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

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. 接口测试

一般来说，接口文档需要完善：接口测试的方法和测试结果，以便用户可以测试接口是否符合自己的需求，让用户用得放心~哈哈