前言

大家,我是田螺。

咱们做后端开发的,常常需求界说接口文档。

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

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

  • 大众号：捡田螺的小男孩 （有田螺精心原创的面试PDF）
  • github地址，感谢每颗star：github

1. 你的接口称号是否明晰？

换句话说，你的接口是做什么的，是否易懂明晰？一般接口url也要求能看得出接口的效果。比方说，查询用户信息（queryUserInfo），便是一个不错的接口称号。

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

2. 你的接口地址是否完好

接口的地址，也叫接口的URL地址。即别人调用你的接口，用的是什么URL。比方/api/user/queryUserInfo便是一个接口地址。可是，我想说的是，这还不是一个完好的接口地址。你的接口是不是HTTP调用呢？

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

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

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

3.你的接口恳求方法是否正确

接口恳求方法一般有以下几种：

  • GET：从服务器获取资源，能够在URL中传递参数，一般用于查询数据。
  • POST：向服务器提交数据，一般用于新增、修改、删除等操作。
  • PUT：向服务器更新资源，一般用于更新数据。
  • DELETE：从服务器删除资源，一般用于删除数据。
  • PATCH：向服务器局部更新资源，一般用于修改部分数据。
  • HEAD：类似于GET恳求，可是只回来呼应头，不回来实体内容，一般用于获取资源的元信息。
  • OPTIONS：恳求服务器回来支持的恳求方法等信息，一般用于客户端与服务端洽谈恳求方法。

你界说接口文档的时分，需求写清楚，你的接口恳求方法是哪一个？一般情况下，咱们用POST和GET比较多。也有些公司的一切接口都用POST恳求。

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

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 用户生日

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

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 数据库过错 数据库访问出错

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

7.接口安全

界说接口文档时，关于一些需求保护的接口，也需求考虑接口的安全，例如权限办理、避免 SQL 注入等。

因而，接口文档应当包括接口的安全性阐明：例如接口的访问授权方法、数据传输加密方法等。此外，接口文档还应该关于敏感数据和操作进行标示，便利运用者留意隐私和安全问题。

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

8. 接口版别办理

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

以下是一些常用的接口版别办理方法：

  • 在接口文档中清晰版别号：在接口文档中清晰标识接口的版别号，例如在接口地址中增加版别号信息，如https://example.com/api/v1/user，表明该接口的版别号为v1。
  • 运用语义化版别号：选用语义化版别号（Semantic Versioning）标准，即版别号格局为X.Y.Z，其中X表明主版别号、Y表明次版别号、Z表明修订号。当进行兼容性改变时，需升级主版别号；当增加功用且不影响现有功用时，需升级次版别号；当进行bug修复或小功用改进时，需升级修订号。
  • 增量发布：在接口发生改变时，先发布新版别的接口，一起保留旧版别的接口。用户能够依据自己的需求来挑选运用哪个版别的接口。跟着新版别的接口逐步替换旧版别的接口，最终能够将旧版别的接口抛弃。

无论选用何种方法，接口版别办理都应该得到充沛的考虑。在接口版别改变时，需求及时更新接口文档（具体描绘版别的改变、兼容性问题、版别切换方法等），以保证用户能够获得最新的接口信息。

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

假如接口发生了改变，比方参数有哪些改变，过错码改变等等，都需求维护到文档上。一起需求挂号改变的记载。

日期 改变描绘 操作人
2023-04-16 创建接口文档，界说了第一版接口文档 捡田螺的小男孩
2023-04-18 修改接口文档，增加了过错码，出参等 田螺哥

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

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

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