接口设计文档的12个注意点

阳光穿透心脏的1/2处 2024-03-23 13:50 52阅读 0赞

### 前言 ###

我们做后端开发的,经常需要**定义接口文档**。

最近在做**接口文档评审**的时候，发现一个小伙伴定义的**出参是个枚举值**，但是接口文档没有给出**对应具体的枚举值**。其实，如何写好接口文档，真的很重要。今天田螺哥，给你带来接口设计文档的`12`个注意点~

![format_png][]

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

换句话说，你的接口是做什么的，是否易懂清晰？一般接口`url`也要求能看得出接口的作用。比如说，**查询用户信息（queryUserInfo）**，就是一个**不错的接口名称**。

![format_png 1][]

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

接口的地址，也叫接口的`URL`地址。即别人调用你的接口，用的是什么`URL`。比如`/api/user/queryUserInfo`就是一个**接口地址**。但是，我想说的是，这还不是一个完整的接口地址。你的接口是不是`HTTP`调用呢？

如果是`HTTP`调用的话，**域名**是什么呢？**端口**呢。一个好的`http`接口地址，应当是这样的：

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

![format_png 2][]

### 3.你的接口请求方式是否正确 ###

接口请求方式通常有以下几种：

*  GET：从服务器获取资源，可以在`URL`中传递参数，通常用于查询数据。
 *  POST：向服务器提交数据，通常用于新增、修改、删除等操作。
 *  PUT：向服务器更新资源，通常用于更新数据。
 *  DELETE：从服务器删除资源，通常用于删除数据。
 *  PATCH：向服务器局部更新资源，通常用于修改部分数据。
 *  HEAD：类似于`GET`请求，但是只返回响应头，不返回实体内容，通常用于获取资源的元信息。
 *  OPTIONS：请求服务器返回支持的请求方式等信息，通常用于客户端与服务端协商请求方式。

你定义接口文档的时候，需要写清楚，你的接口请求方式是哪一个？一般情况下，我们用`POST和GET`比较多。也有些公司的所有接口都用`POST`请求。

![format_png 3][]

### 4.请求参数的8大要素 ###

我们定义接口的时候,请求参数是**最主要的部分之一**。一份合格的接口文档,请求参数应当包含这八大要素:

*  参数名: 参数的名字,都是驼峰命名，比如`userId`。
 *  类型: 参数的类型,比如`String、Integer`等。
 *  是否必填: 请求参数是不是必填的，如果要求必填的，当上游不传这个参数的时候，应当抛参数校验异常。
 *  默认值: 如果这个参数不传，是否有默认值，默认值是多少。
 *  取值范围: 如果是`Long，Integer`等数值类型的话，这个就是一个范围值，比如`1~10`，如果是枚举值的话，那就是枚举范围，比如`ACTIVE、INACTIVE`。
 *  参数格式：比如你的参数是个日期的话，就需要说明参数格式，如`yyyyMMdd`
 *  入参示例值: 提供该响应参数的示例值，以便开发人员更好地理解和使用该参数。
 *  备注: 如果这个入参字段有**特殊说明**的话，可以在这一栏说明。如果没有特殊说明，那只描述这个参数作用也可以。

**以下就是入参的文档样例**：

<table> 
 <thead> 
  <tr> 
   <th>参数名</th> 
   <th>类型</th> 
   <th>是否必填</th> 
   <th>默认值</th> 
   <th>取值范围</th> 
   <th>参数格式</th> 
   <th>入参示例值</th> 
   <th>备注（说明）</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>userId</td> 
   <td>Long</td> 
   <td>是</td> 
   <td>0L</td> 
   <td>0~99999999L</td> 
   <td>无</td> 
   <td>666L</td> 
   <td>用户Id</td> 
  </tr> 
  <tr> 
   <td>birthDay</td> 
   <td>String</td> 
   <td>是</td> 
   <td>19900101</td> 
   <td>19900101~20231231</td> 
   <td>yyyyMMdd</td> 
   <td>19940107</td> 
   <td>用户生日</td> 
  </tr> 
 </tbody> 
</table>

![format_png 4][]

### 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. 接口错误码 ###

一份好的接口文档，一定少不了错误码列举。一般错误码定义包括三列：**错误码、错误码信息、含义**

<table> 
 <thead> 
  <tr> 
   <th>错误码</th> 
   <th>错误信息</th> 
   <th>含义</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>1001</td> 
   <td>参数错误</td> 
   <td>请求参数不合法</td> 
  </tr> 
  <tr> 
   <td>1002</td> 
   <td>用户不存在</td> 
   <td>根据给定的用户ID没有找到对应的用户信息</td> 
  </tr> 
  <tr> 
   <td>1003</td> 
   <td>数据库错误</td> 
   <td>数据库访问出错</td> 
  </tr> 
 </tbody> 
</table>

![format_png 5][]

### 7.接口安全 ###

定义接口文档时，对于一些需要保护的接口，也需要**考虑接口的安全**，例如**权限管理、防止 SQL 注入**等。

因此，接口文档应当包含接口的安全性说明：**例如接口的访问授权方式、数据传输加密方式等。此外，接口文档还应该对于敏感数据和操作进行标注，方便使用者注意隐私和安全问题**。

![format_png 6][]

### 8. 接口版本管理 ###

在接口文档定义时，**接口版本管理是非常重要的一个方面**。由于软件项目的迭代和升级，接口可能会随着版本的变化而发生变化。为了避免接口变化给用户带来不必要的困扰，需要对接口进行版本管理。

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

*  **在接口文档中明确版本号**：在接口文档中明确标识接口的版本号，例如在接口地址中添加版本号信息，如`https://example.com/api/v1/user`，表示该接口的版本号为`v1`。
 *  **使用语义化版本号**：采用语义化版本号（`Semantic Versioning`）规范，即版本号格式为`X.Y.Z`，其中`X`表示主版本号、`Y`表示次版本号、`Z`表示修订号。当进行兼容性变更时，需升级主版本号；当增加功能且不影响现有功能时，需升级次版本号；当进行`bug`修复或小功能改进时，需升级修订号。
 *  **增量发布**：在接口发生变化时，先发布新版本的接口，同时保留旧版本的接口。用户可以根据自己的需求来选择使用哪个版本的接口。随着新版本的接口逐步替换旧版本的接口，最终可以将旧版本的接口废弃。

无论采用何种方法，接口版本管理都应该得到充分的考虑。在接口版本变化时，需要及时更新接口文档（**详细描述版本的变化、兼容性问题、版本切换方式等**），以确保用户能够获得最新的接口信息。

### 9. 维护接口文档更新迭代 ###

如果接口发生了变更，比如**参数有哪些变更，错误码变更等等**，都需要维护到文档上。同时需要**登记变更的记录**。

<table> 
 <thead> 
  <tr> 
   <th>日期</th> 
   <th>变更描述</th> 
   <th>操作人</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>2023-04-16</td> 
   <td>创建接口文档，定义了第一版接口文档</td> 
   <td>捡田螺的小男孩</td> 
  </tr> 
  <tr> 
   <td>2023-04-18</td> 
   <td>修改接口文档，增加了错误码，出参等</td> 
   <td>田螺哥</td> 
  </tr> 
 </tbody> 
</table>

![format_png 7][]

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

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

[format_png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/23/b21a28c128bf4c619c4c45de261c3cab.png
[format_png 1]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/23/b18fcde1fc5e433c981fde17127f86d2.png
[format_png 2]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/23/20dd1ceeb87e4128b8227aaee513dc7b.png
[format_png 3]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/23/3256c3b0185e48698d2fb58f3cdaff79.png
[format_png 4]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/23/bf89d0009b574c218b274ec3fabbabae.png
[format_png 5]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/23/7568c70d49a94b6fa4de4ffbccc8c4d6.png
[format_png 6]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/23/1c050f09f8f84214aa2ce6b31f18de63.png
[format_png 7]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/23/d9cbf2b0eba3478983c16568406a0720.png