接口文档设计的12个注意点
云知 · 3年前
## 前言
大家,我是<strong>田螺</strong>。
我们做后端开发的,经常需要<strong>定义接口文档</strong>。
最近在做<strong>接口文档评审</strong>的时候,发现一个小伙伴定义的<strong>出参是个枚举值</strong>,但是接口文档没有给出<strong>对应具体的枚举值</strong>。其实,如何写好接口文档,真的很重要。今天田螺哥,给你带来接口文档设计的`12`个注意点\~

## 1\. 你的接口名称是否清晰?
换句话说,你的接口是做什么的,是否易懂清晰?一般接口`url`也要求能看得出接口的作用。比如说,<strong>查询用户信息(queryUserInfo)</strong>,就是一个<strong>不错的接口名称</strong>。

## 2\. 你的接口地址是否完整
接口的地址,也叫接口的`URL`地址。即别人调用你的接口,用的是什么`URL`。比如`/api/user/queryUserInfo`就是一个<strong>接口地址</strong>。但是,我想说的是,这还不是一个完整的接口地址。你的接口是不是`HTTP`调用呢?
如果是`HTTP`调用的话,<strong>域名</strong>是什么呢?<strong>端口</strong>呢。一个好的`http`接口地址,应当是这样的:
> `https//tianluo.com:15000/api/user/queryUserInfo`

## 3.你的接口请求方式是否正确
接口请求方式通常有以下几种:
* GET:从服务器获取资源,可以在`URL`中传递参数,通常用于查询数据。
* POST:向服务器提交数据,通常用于新增、修改、删除等操作。
* PUT:向服务器更新资源,通常用于更新数据。
* DELETE:从服务器删除资源,通常用于删除数据。
* PATCH:向服务器局部更新资源,通常用于修改部分数据。
* HEAD:类似于`GET`请求,但是只返回响应头,不返回实体内容,通常用于获取资源的元信息。
* OPTIONS:请求服务器返回支持的请求方式等信息,通常用于客户端与服务端协商请求方式。
你定义接口文档的时候,需要写清楚,你的接口请求方式是哪一个?一般情况下,我们用`POST和GET`比较多。也有些公司的所有接口都用`POST`请求。

## 4.请求参数的8大要素
我们定义接口的时候,请求参数是<strong>最主要的部分之一</strong>。一份合格的接口文档,请求参数应当包含这八大要素:
* 参数名: 参数的名字,都是驼峰命名,比如`userId`。
* 类型: 参数的类型,比如`String、Integer`等。
* 是否必填: 请求参数是不是必填的,如果要求必填的,当上游不传这个参数的时候,应当抛参数校验异常。
* 默认值: 如果这个参数不传,是否有默认值,默认值是多少。
* 取值范围: 如果是`Long,Integer`等数值类型的话,这个就是一个范围值,比如`1~10`,如果是枚举值的话,那就是枚举范围,比如`ACTIVE、INACTIVE`。
* 参数格式:比如你的参数是个日期的话,就需要说明参数格式,如`yyyyMMdd`
* 入参示例值: 提供该响应参数的示例值,以便开发人员更好地理解和使用该参数。
* 备注: 如果这个入参字段有<strong>特殊说明</strong>的话,可以在这一栏说明。如果没有特殊说明,那只描述这个参数作用也可以。
<strong>以下就是入参的文档样例</strong>:
| 参数名 | 类型 | 是否必填 | 默认值 | 取值范围 | 参数格式 | 入参示例值 | 备注(说明) |
| --- | --- | ---- | --- | ---- | ---- | ----- | ------ |
| userId | Long | 是 | 0L | 0\~99999999L | 无 | 666L | 用户Id |
| birthDay | String | 是 | 19900101 | 19900101\~20231231 | yyyyMMdd | 19940107 | 用户生日 |

## 5.响应参数的7大要求
响应参数其实跟入参差不多,有7种要素:
* 参数名称:描述该响应参数的名称。
* 参数类型:描述该响应参数的数据类型,如`String、Integer`等。
* 参数格式:描述该响应参数的数据格式,如`yyyy-MM-dd、HH:mm:ss`等。
* 参数说明:对该响应参数的含义进行详细的描述。
* 取值范围:描述该响应参数的取值范围,如<strong>整数范围、字符串长度</strong>等。
* 是否必填:描述该响应参数是否为必填项。
* 示例值:提供该响应参数的示例值,以便开发人员更好地理解和使用该参数。
不一样的地方是,响应参数,一般都是按照`code,msg,data`的格式返回的:
```
{
"code": 0,
"message": "success",
"data": {
"name": "Tom",
"age": 20,
"gender": "男"
}
}
```
## 6\. 接口错误码
一份好的接口文档,一定少不了错误码列举。一般错误码定义包括三列:<strong>错误码、错误码信息、含义</strong>
| 错误码 | 错误信息 | 含义 |
| --- | ---- | --- |
| 1001 | 参数错误 | 请求参数不合法 |
| 1002 | 用户不存在 | 根据给定的用户ID没有找到对应的用户信息 |
| 1003 | 数据库错误 | 数据库访问出错 |

## 7.接口安全
定义接口文档时,对于一些需要保护的接口,也需要<strong>考虑接口的安全</strong>,例如<strong>权限管理、防止 SQL 注入</strong>等。
因此,接口文档应当包含接口的安全性说明:<strong>例如接口的访问授权方式、数据传输加密方式等。此外,接口文档还应该对于敏感数据和操作进行标注,方便使用者注意隐私和安全问题</strong>。

## 8\. 接口版本管理
在接口文档定义时,<strong>接口版本管理是非常重要的一个方面</strong>。由于软件项目的迭代和升级,接口可能会随着版本的变化而发生变化。为了避免接口变化给用户带来不必要的困扰,需要对接口进行版本管理。
以下是一些常用的接口版本管理方法:
* <strong>在接口文档中明确版本号</strong>:在接口文档中明确标识接口的版本号,例如在接口地址中添加版本号信息,如`https://example.com/api/v1/user`,表示该接口的版本号为`v1`。
* <strong>使用语义化版本号</strong>:采用语义化版本号(`Semantic Versioning`)规范,即版本号格式为`X.Y.Z`,其中`X`表示主版本号、`Y`表示次版本号、`Z`表示修订号。当进行兼容性变更时,需升级主版本号;当增加功能且不影响现有功能时,需升级次版本号;当进行`bug`修复或小功能改进时,需升级修订号。
* <strong>增量发布</strong>:在接口发生变化时,先发布新版本的接口,同时保留旧版本的接口。用户可以根据自己的需求来选择使用哪个版本的接口。随着新版本的接口逐步替换旧版本的接口,最终可以将旧版本的接口废弃。
无论采用何种方法,接口版本管理都应该得到充分的考虑。在接口版本变化时,需要及时更新接口文档(<strong>详细描述版本的变化、兼容性问题、版本切换方式等</strong>),以确保用户能够获得最新的接口信息。
## 9\. 维护接口文档更新迭代
如果接口发生了变更,比如<strong>参数有哪些变更,错误码变更等等</strong>,都需要维护到文档上。同时需要<strong>登记变更的记录</strong>。

| 日期 | 变更描述 | 操作人 |
| --- | ---- | --- |
| 2023-04-16 | 创建接口文档,定义了第一版接口文档 | 捡田螺的小男孩 |
| 2023-04-18 | 修改接口文档,增加了错误码,出参等 | 田螺哥 |
## 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 接口请求示例
接口文档,需要提供接口的使用案例:<strong>以方便开发者理解接口的使用方法和调用流程</strong>。
## 12\. 接口测试
一般来说,接口文档需要完善:接口测试的方法和测试结果,以便用户可以测试接口是否符合自己的需求,让用户用得放心\~哈哈
资讯来源:https://mp.weixin.qq.com/s/hHXmvTbS1sy_yJRHztofxQ
推荐资讯
-
对话无损的秘密:ThinkChat 的上下文优化之道
2026年06月11日
-
ThinkChat 空间知识库技能:让每个团队都拥有自己的"企业大脑"
2026年06月07日
-
ThinkChat IM频道上线——你随身超级工作助理
2026年06月07日
-
你的AI助理,终于能帮你"上网干活"了
2026年05月11日
-
ThinkChat 工作空间:让 AI 成为真正的团队成员
2026年05月07日
最新资讯
-
对话无损的秘密:ThinkChat 的上下文优化之道
2026年06月11日
-
ThinkChat 空间知识库技能:让每个团队都拥有自己的"企业大脑"
2026年06月07日
-
ThinkChat IM频道上线——你随身超级工作助理
2026年06月07日
-
你的AI助理,终于能帮你"上网干活"了
2026年05月11日
-
ThinkChat 工作空间:让 AI 成为真正的团队成员
2026年05月07日