• 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
• 入参示例值：提供该响应参数的示例值，以便开发人员更好地理解和使用该参数。
• 备注：如果这个入参字段有特殊说明 的话，可以在这一栏说明。如果没有特殊说明，那只描述这个参数作用也可以。

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