冷门但必备的知识：接口文档中如何正确写“说明”

撒乎乎不撒

已于 2024-12-15 00:17:22 修改

阅读量1k

点赞数 28

分类专栏：高效学习文章标签： spring boot mvc

于 2024-12-14 23:26:52 首次发布

本文链接：https://blog.youkuaiyun.com/2403_89128801/article/details/144478423

版权

高效学习专栏收录该内容

13 篇文章

订阅专栏

冷门但必备的知识：接口文档中如何正确写“说明”

清晰准确的“说明”不仅为开发者提供高效的使用指南，还能促进团队沟通，减少不必要的误解与开发成本。

在这里插入图片描述

1. 聚焦接口功能，避免过多技术细节

接口文档的重点是 描述 接口的功能，而不是后台的实现细节。开发者关注的是如何通过接口完成任务，而非接口背后的数据处理或复杂逻辑。

错误例子

描述复杂的后台数据处理逻辑，这种描述容易让开发者困惑，从而 干扰 他们对接口功能的理解。

示例

*说明：当前用户的弹幕屏蔽列表*
 ## 两种屏蔽方式：
	1. 屏蔽单条弹幕
	2. 屏蔽该弹幕的发送者的所有弹幕
## 后端处理逻辑：
	1. 如果屏蔽的是单条弹幕，则直接在弹幕屏蔽列表资源(`danmu_sheild`)进行创建操作。
	2. 如果屏蔽的是某个用户的所有弹幕，系统首先查询该用户的编号，然后返回其发送的所有弹幕编号，再将这些编号添加到弹幕屏蔽列表资源(`danmu_sheild`)中。
	3. 弹幕编号应采用数组格式进行装载。

问题分析
示例中，文档详细描述了如何在后台处理屏蔽逻辑，涉及到数据库查询、数据格式要求以及系统的内部操作。这些细节对开发者来说并不直接相关，反而可能增加理解难度。

正确例子

接口文档应专注于接口的功能，清晰地说明如何通过接口完成任务，而不是如何实现任务的技术细节。

正确示例

接口功能：屏蔽弹幕

请求参数：

{
  "danmu_id": "12345",
  "blockUser": false
}

说明：
- danmu_id：需要屏蔽的弹幕的唯一标识符。如果blockUser为true，则表示屏蔽该用户的所有弹幕。
- blockUser：布尔值，表示是否屏蔽该用户的所有弹幕。如果为false，仅屏蔽单条弹幕。

重点

功能说明
该说明重点描述了该接口的作用，即屏蔽弹幕，所需的请求参数及其意义。
避免技术细节
后台如何查询和处理数据、如何在数据库中操作等细节不在文档中提及。开发者只需知道如何传递参数然后实现细节由他们自己来思考, 即可。

2. 简化流程，清晰易懂

某些接口可能在实现中涉及多个步骤，但文档不必详细展开每个技术实现，只需简洁描述操作流程，帮助开发者理解整体顺序即可。

错误示例

描述过多的技术实现细节，使开发者难以理解整体流程。

错误示例

## 操作流程
1. 向用户发送注册确认邮件，邮件内容包含注册链接。
2. 用户点击注册链接，系统验证链接有效性，确认用户身份。
3. 确认身份后，向数据库中插入用户信息，创建账号。
4. 发送注册成功的通知邮件给用户。

问题分析
这种描述包含了太多的技术实现细节，如邮件发送、链接验证和数据库操作，使得开发者难以快速理解整体的注册流程。

正确示例

简化的操作流程描述，聚焦于整体顺序而非每个具体细节。

正确示例

##操作流程
步骤 1：发送用户注册请求。
步骤 2：接收服务器响应，确认账号创建成功。

重点
1. 简洁明了
  仅描述用户如何发送注册请求以及如何确认账号创建成功，避免过多技术实现细节。
2. 帮助理解：
  开发者能够快速了解整体注册流程，而无需关注每个步骤背后的具体实现细节。

3. 区分说明与实现

清晰区分接口功能说明和其内部的技术实现，能够帮助开发者快速理解接口，而不被淹没在整个应用内部的复杂实现细节中。

功能说明

接口说明应集中于描述外部行为，即接口如何被调用、请求的输入及响应的输出格式。这部分信息对开发者来说是最直接和实用的，也是友好的。

例

接口功能
创建用户账号

请求参数

{
  "username": "user123",
  "password": "password123"
}

说明：
- username：用户的用户名，必须唯一。
- password：用户的密码。

技术实现

技术实现部分则详细描述了接口背后的 实现细节，包括数据库查询、业务逻辑处理等复杂内容。这些细节对于开发者理解系统内部的原理是有帮助的，但对于接口的使用者并不必要。

解决
在文档中不包括技术实现，而是聚焦功能说明和简洁的示例。技术实现可以单独放在技术文档或开发手册中，供需要的开发人员参考。总之，技术说明应当和功能说明独立分开，功能文档专注于说明，技术文档专注于实现

4. 总结

接口文档的核心目标是帮助开发者理解和使用接口，而非了解其内部实现。因此，撰写高质量的“说明”部分时，应该:

聚焦接口功能
- 清晰描述接口的功能和用途，避免不必要的技术实现细节。
- 开发者最关心的是如何调用接口以及如何实现业务需求，而非接口背后的逻辑运作。
简化流程，清晰易懂
- 对涉及多步骤的流程，简要列出操作顺序，帮助开发者快速理解接口的整体行为。
- 避免过于详细的技术实现描述，以免让开发者迷失在不相关的细节中。
区分说明与实现
- 将功能说明与技术实现分开。
- 功能说明侧重于接口的输入、输出及外部行为，确保开发者能直观了解接口的用法。
  简化流程，清晰易懂
- 对涉及多步骤的流程，简要列出操作顺序，帮助开发者快速理解接口的整体行为。
- 避免过于详细的技术实现描述，以免让开发者迷失在不相关的细节中。