接口文档设计的12个注意点！
点击上方“芋道源码”，选择“设为星标”
管她前浪，还是后浪？
能浪的浪，才是好浪！
每天 10:33 更新文章，每天掉亿点点头发...
源码精品专栏
1. 你的接口名称是否清晰 2. 你的接口地址是否完整 3. 你的接口请求方式是否正确 4. 请求参数的8大要素 5. 响应参数的7大要求 6. 接口错误码完整 7. 接口安全描述 8. 接口版本管理 9. 维护接口文档更新迭代 10. 明确请求头有哪些 11. 写清楚接口请求示例 12. 完善接口测试方法和结果
后端开发，经常需要定义接口文档 。如何写好接口文档，真的很重要。
今天给大家带来接口文档设计的12个注意点~
1. 你的接口名称是否清晰
换句话说，你的接口是做什么的，是否易懂清晰？一般接口url也要求能看得出接口的作用。比如说，查询用户信息（queryUserInfo） ，就是一个不错的接口名称 。
基于 Spring Boot + MyBatis Plus + Vue & Element 实现的后台管理系统 + 用户小程序，支持 RBAC 动态权限、多租户、数据权限、工作流、三方登录、支付、短信、商城等功能
项目地址：https://github.com/YunaiV/ruoyi-vue-pro 视频教程：https://doc.iocoder.cn/video/
2. 你的接口地址是否完整
接口的地址，也叫接口的URL地址。即别人调用你的接口，用的是什么URL。比如/api/user/queryUserInfo就是一个接口地址 。但是，我想说的是，这还不是一个完整的接口地址。你的接口是不是HTTP调用呢？
如果是HTTP调用的话，域名 是什么呢？端口 呢？一个好的http接口地址，应当是这样的：
https://tianluo.com:15000/api/user/queryUserInfo
基于 Spring Cloud Alibaba + Gateway + Nacos + RocketMQ + Vue & Element 实现的后台管理系统 + 用户小程序，支持 RBAC 动态权限、多租户、数据权限、工作流、三方登录、支付、短信、商城等功能
项目地址：https://github.com/YunaiV/yudao-cloud 视频教程：https://doc.iocoder.cn/video/
3. 你的接口请求方式是否正确
接口请求方式通常有以下几种：
GET：从服务器获取资源，可以在 URL中传递参数，通常用于查询数据。POST：向服务器提交数据，通常用于新增、修改、删除等操作。 PUT：向服务器更新资源，通常用于更新数据。 DELETE：从服务器删除资源，通常用于删除数据。 PATCH：向服务器局部更新资源，通常用于修改部分数据。 HEAD：类似于 GET请求，但是只返回响应头，不返回实体内容，通常用于获取资源的元信息。OPTIONS：请求服务器返回支持的请求方式等信息，通常用于客户端与服务端协商请求方式。
你定义接口文档的时候，需要写清楚，你的接口请求方式是哪一个？一般情况下，我们用POST和GET比较多。也有些公司的所有接口都用POST请求。
4. 请求参数的8大要素
我们定义接口的时候，请求参数是最主要的部分之一 。一份合格的接口文档，请求参数应当包含这八大要素：
参数名：参数的名字，都是驼峰命名，比如 userId。类型：参数的类型，比如 String、Integer等。是否必填：请求参数是不是必填的，如果要求必填的，当上游不传这个参数的时候，应当抛参数校验异常。 默认值：如果这个参数不传，是否有默认值，默认值是多少。 取值范围：如果是 Long、Integer等数值类型的话，这个就是一个范围值，比如1~10，如果是枚举值的话，那就是枚举范围，比如ACTIVE、INACTIVE。参数格式：比如你的参数是个日期的话，就需要说明参数格式，如 yyyyMMdd入参示例值：提供该响应参数的示例值，以便开发人员更好地理解和使用该参数。 备注：如果这个入参字段有特殊说明 的话，可以在这一栏说明。如果没有特殊说明，那只描述这个参数作用也可以。
以下就是入参的文档样例 ：
| 参数名 | 类型 | 是否必填 | 默认值 | 取值范围 | 参数格式 | 入参示例值 | 备注（说明） |
|---|---|---|---|---|---|---|---|
| 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等。参数说明：对该响应参数的含义进行详细的描述。 取值范围：描述该响应参数的取值范围，如整数范围、字符串长度 等。 是否必填：描述该响应参数是否为必填项。 示例值：提供该响应参数的示例值，以便开发人员更好地理解和使用该参数。
不一样的地方是，响应参数一般都是按照code，msg，data的格式返回的：
{
"code": 0,
"message": "success",
"data": {
"name": "Tom",
"age": 20,
"gender": "男"
}
}
6. 接口错误码完整
一份好的接口文档，一定少不了错误码列举。一般错误码定义包括三列：错误码、错误码信息、含义 。
| 错误码 | 错误信息 | 含义 |
|---|---|---|
| 1001 | 参数错误 | 请求参数不合法 |
| 1002 | 用户不存在 | 根据给定的用户ID没有找到对应的用户信息 |
| 1003 | 数据库错误 | 数据库访问出错 |
7. 接口安全描述
定义接口文档时，对于一些需要保护的接口，也需要考虑接口的安全 ，例如权限管理、防止 SQL 注入 等。
因此，接口文档应当包含接口的安全性说明：例如接口的访问授权方式、数据传输加密方式等。此外，接口文档还应该对于敏感数据和操作进行标注，方便使用者注意隐私和安全问题 。
8. 接口版本管理
在接口文档定义时，接口版本管理是非常重要的一个方面 。由于软件项目的迭代和升级，接口可能会随着版本的变化而发生变化。为了避免接口变化给用户带来不必要的困扰，需要对接口进行版本管理。
以下是一些常用的接口版本管理方法：
在接口文档中明确版本号 ：在接口文档中明确标识接口的版本号，例如在接口地址中添加版本号信息，如 https://example.com/api/v1/user，表示该接口的版本号为v1。使用语义化版本号 ：采用语义化版本号（ Semantic Versioning）规范，即版本号格式为X.Y.Z，其中X表示主版本号、Y表示次版本号、Z表示修订号。当进行兼容性变更时，需升级主版本号；当增加功能且不影响现有功能时，需升级次版本号；当进行bug修复或小功能改进时，需升级修订号。增量发布 ：在接口发生变化时，先发布新版本的接口，同时保留旧版本的接口。用户可以根据自己的需求来选择使用哪个版本的接口。随着新版本的接口逐步替换旧版本的接口，最终可以将旧版本的接口废弃。
无论采用何种方法，接口版本管理都应该得到充分的考虑。在接口版本变化时，需要及时更新接口文档（详细描述版本的变化、兼容性问题、版本切换方式等 ），以确保用户能够获得最新的接口信息。
9. 维护接口文档更新迭代
如果接口发生了变更，比如参数有哪些变更、错误码变更等等 ，都需要维护到文档上。同时需要登记变更的记录 。
| 日期 | 变更描述 | 操作人 |
|---|---|---|
| 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": "[email protected]"}
11. 写清楚接口请求示例
接口文档，需要提供接口的使用案例：以方便开发者理解接口的使用方法和调用流程 。
12. 完善接口测试方法和结果
一般来说，接口文档需要完善接口测试的方法和结果，以便用户可以测试接口是否符合自己的需求，让用户用得放心。
欢迎加入我的知识星球，一起探讨架构，交流源码。加入方式，长按下方二维码噢：
已在知识星球更新源码解析如下：
最近更新《芋道 SpringBoot 2.X 入门》系列，已经 101 余篇，覆盖了 MyBatis、Redis、MongoDB、ES、分库分表、读写分离、SpringMVC、Webflux、权限、WebSocket、Dubbo、RabbitMQ、RocketMQ、Kafka、性能测试等等内容。
提供近 3W 行代码的 SpringBoot 示例，以及超 4W 行代码的电商微服务项目。
获取方式：点“在看”，关注公众号并回复 666 领取，更多内容陆续奉上。
文章有帮助的话，在看，转发吧。
谢谢支持哟 (*^__^*）
微信扫码关注该文公众号作者