草庐IT

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

捡田螺的小男孩 2023-08-21 原文

​前言

大家,我是田螺。

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

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

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

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

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

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

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

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

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": "john.doe@example.com"}

11 接口请求示例

接口文档，需要提供接口的使用案例：以方便开发者理解接口的使用方法和调用流程。

12. 接口测试

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

接口个data-iddataspan开发前端文档设计

有关接口文档设计的12个注意点的更多相关文章

  1. ruby-on-rails - Rails - 子类化模型的设计模式是什么？ - 2

    我有一个模型:classItem项目有一个属性“商店”基于存储的值，我希望Item对象对特定方法具有不同的行为。Rails中是否有针对此的通用设计模式？如果方法中没有大的if-else语句，这是如何干净利落地完成的？ 最佳答案 通常通过Single-TableInheritance. 关于ruby-on-rails-Rails-子类化模型的设计模式是什么？，我们在StackOverflow上找到一个类似的问题： https://stackoverflow.co

  2. ruby-on-rails - 使用 rails 4 设计而不更新用户 - 2

    我将应用程序升级到Rails4，一切正常。我可以登录并转到我的编辑页面。也更新了观点。使用标准View时，用户会更新。但是当我添加例如字段:name时，它​​不会在表单中更新。使用devise3.1.1和gem'protected_attributes'我需要在设备或数据库上运行某种更新命令吗？我也搜索过这个地方，找到了许多不同的解决方案，但没有一个会更新我的用户字段。我没有添加任何自定义字段。 最佳答案 如果您想允许额外的参数，您可以在ApplicationController中使用beforefilter，因为Rails4将参数

  3. Matlab imread（）读到了什么 （浅显 当复习文档了） - 2

    matlab打开matlab，用最简单的imread方法读取一个图像clcclearimg_h=imread('hua.jpg');返回一个数组（矩阵），往往是a*b*cunit8类型解释一下这个三维数组的意思，行数、数和层数，unit8：指数据类型，无符号八位整形，可理解为0~2^8的数三个层数分别代表RGB三个通道图像rgb最常用的是24-位实现方法，即RGB每个通道有256色阶（2^8）。基于这样的24-位RGB模型的色彩空间可以表现256×256×256≈1670万色当imshow传入了一个二维数组，它将以灰度方式绘制；可以把图像拆分为rgb三层，可以以灰度的方式观察它figure(1

  4. postman接口测试工具-基础使用教程 - 2

    1.postman介绍Postman一款非常流行的API调试工具。其实，开发人员用的更多。因为测试人员做接口测试会有更多选择，例如Jmeter、soapUI等。不过，对于开发过程中去调试接口，Postman确实足够的简单方便，而且功能强大。2.下载安装官网地址:https://www.postman.com/下载完成后双击安装吧，安装过程极其简单，无需任何操作3.使用教程这里以百度为例,工具使用简单，填写URL地址即可发送请求，在下方查看响应结果和响应状态码常用方法都有支持请求方法:getpostputdeleteGet、Post、Put与Delete的作用get：请求方法一般是用于数据查询，

  5. LC滤波器设计学习笔记（一）滤波电路入门 - 2

    目录前言滤波电路科普主要分类实际情况单位的概念常用评价参数函数型滤波器简单分析滤波电路构成低通滤波器RC低通滤波器RL低通滤波器高通滤波器RC高通滤波器RL高通滤波器部分摘自《LC滤波器设计与制作》，侵权删。前言最近需要学习放大电路和滤波电路，但是由于只在之前做音乐频谱分析仪的时候简单了解过一点点运放，所以也是相当从零开始学习了。滤波电路科普主要分类滤波器：主要是从不同频率的成分中提取出特定频率的信号。有源滤波器：由RC元件与运算放大器组成的滤波器。可滤除某一次或多次谐波，最普通易于采用的无源滤波器结构是将电感与电容串联，可对主要次谐波（3、5、7）构成低阻抗旁路。无源滤波器：无源滤波器，又称

  6. 计算机毕业设计ssm+vue基本微信小程序的小学生兴趣延时班预约小程序 - 2

    项目介绍随着我国经济迅速发展,人们对手机的需求越来越大,各种手机软件也都在被广泛应用,但是对于手机进行数据信息管理,对于手机的各种软件也是备受用户的喜爱小学生兴趣延时班预约小程序的设计与开发被用户普遍使用,为方便用户能够可以随时进行小学生兴趣延时班预约小程序的设计与开发的数据信息管理,特开发了小程序的设计与开发的管理系统。小学生兴趣延时班预约小程序的设计与开发的开发利用现有的成熟技术参考,以源代码为模板,分析功能调整与小学生兴趣延时班预约小程序的设计与开发的实际需求相结合,讨论了小学生兴趣延时班预约小程序的设计与开发的使用。开发环境开发说明：前端使用微信微信小程序开发工具：后端使用ssm：VU

  7. 阿里云国际版免费试用：如何注册以及注意事项 - 2

    作为新的阿里云用户，您可以50免费试用多种优惠，价值高达1,700美元（或8,500美元）。这将让您了解和体验阿里云平台上提供的一系列产品和服务。如果您以个人身份注册免费试用，您将获得价值1,700美元的优惠。但是，如果您是注册公司，您可以选择企业免费试用，提交基本信息通过企业实名注册验证，即可开始价值$8,500的免费试用！本教程介绍了如何设置您的帐户并使用您的免费试用版。​关于免费试用在我们开始此试用之前，您还必须遵守以下条款和条件才能访问您的免费试用：只有在一年内创建的账户才有资格获得阿里云免费试用。通过此免费试用优惠，用户可以免费试用免费试用活动页面上列出的每种产品一次。如果您有多个帐

  8. ruby-on-rails - 设计注册确认 - 2

    我在我的项目中有一个用户和一个管理员角色。我使用Devise创建了身份验证。在我的管理员角色中，我没有任何确认。在我的用户模型中，我有以下内容:devise:database_authenticatable,:confirmable,:recoverable,:rememberable,:trackable,:validatable,:timeoutable,:registerable#Setupaccessible(orprotected)attributesforyourmodelattr_accessible:email,:username,:prename,:surname,:

  9. Ruby 等同于 Sphinx 文档生成器？ - 2

    Ruby有一些不错的文档生成器，例如Yard、rDoc，甚至Glyph。问题是Sphinx可以做网站、PDF、epub、LaTex等。它在重组文本中完成所有这些事情。在Ruby世界中有替​​代方案吗？也许是程序的组合？如果我也能使用Markdown就更好了。 最佳答案 自1.0版以来，Sphinx有了“域”的概念，它是从Python和/或C以外的语言标记代码实体(如方法调用、对象、函数等)的方法。有一个rubydomain,所以你可以只使用Sphinx本身。您唯一会缺少的(我认为)是Sphinx使用autodoc从源代码自动创建文档

  10. ruby-on-rails - 设计通过 reset_password_token 获取用户 - 2

    我正在尝试创建密码规则来设计可恢复的密码更改。我通过passwords_controller.rb做了一个父类(superclass)，但我需要在应用规则之前检查用户角色，但我所拥有的只是reset_password_token。 最佳答案 假设您的模型是用户:User.with_reset_password_token(your_token_here)Source 关于ruby-on-rails-设计通过reset_password_token获取用户，我们在StackOverflow

随机推荐