系列文章：程序员 AI 效率笔记 | 第五篇

接口文档是前后端协作的基础，但大多数程序员不爱写。接口改了文档忘更新，字段描述要么没有要么过时，新人来了只能看代码猜接口含义。AI 可以帮程序员根据代码快速生成接口文档、补全字段说明、统一格式，让写文档这件事从"负担"变成"顺手的事"。

为什么接口文档总是缺失或过时

接口文档的重要性不需要解释，但现实中大多数项目的接口文档要么不全，要么是过时的。

原因通常有几个：

• 写代码的时候功能还在变，文档写早了要反复改

• 功能做完了赶着上线，文档往后排就再也没补

• 接口一改，代码更新了但文档没人跟着更新

• Swagger 注解写起来啰嗦，很多人懒得写全

• 字段描述要写中文，代码里全是英文，两边对不上

结果就是：前端靠 Postman 自己试，新人靠问老人，接口文档变成了摆设。

AI 适合帮你做哪些接口文档工作

1. 根据 Controller 代码生成接口描述

你把接口代码发给 AI，它可以提取路径、请求方式、参数、返回值，生成结构化的接口文档。

2. 补全字段中文说明

代码里的字段名是英文，AI 可以根据上下文推断含义并补上中文描述。

3. 生成请求和响应示例

AI 可以根据参数类型和业务场景，生成合理的请求和响应 JSON 示例。

4. 统一文档格式

不同人写的文档格式不一样，AI 可以帮你统一成固定模板。

5. 根据接口变更生成更新说明

把新旧代码对比发给 AI，让它总结接口变更内容，直接作为更新日志。

实际操作：从代码到接口文档

第一步：把接口代码发给 AI，生成基础文档

最简单的做法是把 Controller 方法代码直接发给 AI。

比如你有一个查询订单列表的接口：

@GetMapping("/api/orders")
public PageResult<OrderVO> listOrders(
    @RequestParam(required = false) String status,
    @RequestParam(defaultValue = "1") int page,
    @RequestParam(defaultValue = "20") int pageSize) {
    return orderService.listOrders(status, page, pageSize);
}

提示词：

请根据下面的 Spring Boot 接口代码生成接口文档。
要求包含：接口路径、请求方式、参数说明（含是否必填和默认值）、返回值结构、字段中文描述。
格式用 Markdown 表格。

AI 会生成类似这样的文档：

### 查询订单列表
​
- 路径：GET /api/orders
- 描述：分页查询订单列表，支持按状态筛选
​
**请求参数：**
​
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| status | String | 否 | - | 订单状态筛选 |
| page | int | 否 | 1 | 页码 |
| pageSize | int | 否 | 20 | 每页条数 |

你只需要检查字段描述是否准确，补充 AI 猜不到的业务含义。

第二步：让 AI 补全字段的中文描述

把 VO 代码发给 AI：

public class OrderVO {
    private String orderId;
    private String userId;
    private BigDecimal totalAmount;
    private String status;
    private LocalDateTime createTime;
    private LocalDateTime payTime;
    private String remark;
}

提示词：

请为下面 Java 类的每个字段补充中文描述，格式用注释形式写在字段上方。
如果字段含义不确定，标注"待确认"。

对于含义模糊的字段（比如 status 的枚举值），AI 会标注出来提醒你补充。

第三步：生成请求和响应 JSON 示例

提示词：

根据上面的接口文档，生成一个完整的请求示例和成功响应示例。
请求参数用实际业务场景的值，不要用 test、123 这种占位数据。
响应示例包含 2-3 条数据。

AI 会生成贴近真实业务的 JSON 示例，比你自己编数据快得多。

第四步：批量处理多个接口

如果你有一整个 Controller 文件需要生成文档，可以一次性发给 AI：

下面是一个完整的 OrderController，包含 5 个接口。
请为每个接口生成文档，格式统一，包含：路径、方式、参数表、返回值表、请求示例、响应示例。
接口之间用二级标题分隔。

对于大型项目，可以按模块分批生成，最后合并成完整的接口文档。

第五步：让 AI 生成 Swagger 注解

如果你的项目用 Swagger/OpenAPI，手写注解很繁琐。可以让 AI 帮你补全：

请为下面的接口方法添加 Swagger 3（OpenAPI）注解。
包含 @Operation、@Parameter、@Schema 注解，description 用中文。

AI 会在你的代码上补全注解，你只需要复制回去。

检查 AI 生成的文档，重点看这几个地方

• 字段含义是否准确：AI 根据字段名推断含义，但 status 的枚举值、amount 含税与否，它不知道

• 敏感信息：代码如果涉及内部域名、密钥、真实用户数据，发给 AI 之前要先脱敏

• 文档和代码同步：AI 帮你降低了写文档的成本，但更新文档还是需要人去触发

• 格式统一：先定好模板，再让 AI 按模板填充，效果更好

总结

程序员用 AI 写接口文档，最大的价值是把"写文档"从一件需要额外安排时间的工作，变成写完代码顺手就能做的事。

合理的分工是：

AI 负责提取接口结构、生成格式统一的文档和示例，程序员负责确认业务含义和补充 AI 猜不到的细节。

只要把"代码写完→发给 AI 生成文档→人工过一遍"这个流程跑顺，接口文档就不再是负担了。

#AI编程助手# #接口文档# #SpringBoot# #Swagger# #程序员效率#