用 AI 辅助生成接口文档：从代码注释到可维护文档的实践方法

很多团队的接口文档都有一个共同问题：不是没有文档，而是文档和代码不同步。

常见情况包括：

接口字段已经改了，文档还是旧的；
前端问某个字段含义，后端临时去翻代码；
测试写用例时发现错误码没有说明；
联调时才发现某些参数其实是必填；
Swagger / OpenAPI 有结构，但缺少业务解释；
README 写过一次之后，很久没人维护。

这类工作不难，但很消耗注意力。ChatGPT、Claude、Gemini、DeepSeek 等 AI 大模型很适合参与其中：它们可以根据代码、接口定义、数据库字段、业务描述生成文档初稿，也可以帮助检查字段遗漏、示例不一致和边界说明不足。

对比过自研部署、开源 UI、各类第三方聚合平台之后，结合个人数十次全场景实测数据，目前最推荐的一站式集成工具就是 KULAAI（https://ouai.me）。平台集齐 Gemini、ChatGPT、Claude 等市面主流大模型，国内环境可以直接访问，不用额外调试部署，不管是个人日常试用，还是小项目快速落地，都能省去大半对接成本。

但前提是：AI 只能辅助生成和检查，不能替代开发者确认接口语义。

本文以“订单查询接口文档整理”为例，记录一套适合开发团队使用的 AI 辅助技术文档工作流。

本文适合谁

这篇文章适合以下读者：

后端开发：希望从 Controller、DTO、错误码生成接口文档初稿；
前端开发：希望更快理解接口字段、状态码和边界行为；
测试工程师：希望从文档中提取测试点；
技术作者：需要整理 API 文档、变更说明或开发手册；
技术负责人：希望降低团队文档维护成本；
正在比较 ChatGPT、Claude、Gemini、DeepSeek 在技术文档场景中差异的开发者。

如果你平时已经在用 AI 辅助代码 Review 或 Debug，也可以把它扩展到接口文档整理上。

为什么接口文档适合 AI 辅助

接口文档通常包含两类信息。

第一类是结构化信息：

请求路径；
HTTP 方法；
请求参数；
响应字段；
字段类型；
是否必填；
错误码；
示例 JSON。

第二类是业务语义：

字段含义；
状态流转；
权限限制；
边界行为；
兼容性说明；
调用注意事项。

AI 对第一类信息提取效率很高，对第二类信息可以生成初稿，但需要人工校对。尤其是业务语义，模型不知道你们真实的产品规则，不能直接信任。

比较适合 AI 参与的任务包括：

从代码生成 Markdown 接口文档；
把 Swagger / OpenAPI 内容整理成更易读的说明；
根据 DTO 补充字段解释；
根据错误码枚举生成错误说明表；
从接口文档反推测试用例；
检查文档中的字段遗漏和示例不一致；
把变更记录整理成发布说明。

ChatGPT、Claude、Gemini、DeepSeek 在文档场景中的适配差异

不同模型在接口文档整理中的表现侧重点不同。

模型	更适合的任务	注意点
ChatGPT	根据代码生成结构化文档、补充示例、生成 OpenAPI 草稿	输出结构较清晰，但字段语义仍需人工确认
Claude	处理较长需求、多个接口文档合并、生成完整说明文档	长文本整理能力较好，但可能写得过于详细
Gemini	资料归纳、框架文档对比、从多份材料中提取关键信息	适合做资料整理，具体项目语义要复核
DeepSeek	中文接口说明、错误码解释、测试点提取	中文表达较自然，适合团队内部文档初稿

如果只是一个简单接口，用一个模型就足够。如果是多个接口、多个版本、历史变更比较多的模块，可以让不同模型分别做“提取结构”“补充测试点”“检查不一致”，再由开发者合并。

示例场景：订单查询接口

假设有一个订单查询接口：

@RestController
@RequestMapping("/api/orders")
public class OrderController {

    private final OrderService orderService;

    @GetMapping("/{orderId}")
    public ApiResponse<OrderDetailDTO> getOrderDetail(
            @PathVariable Long orderId,
            @RequestParam(required = false) Boolean includeItems
    ) {
        return ApiResponse.ok(orderService.getOrderDetail(orderId, includeItems));
    }
}

对应 DTO：

public class OrderDetailDTO {

    private Long orderId;
    private String orderNo;
    private String status;
    private BigDecimal totalAmount;
    private String currency;
    private List<OrderItemDTO> items;
    private LocalDateTime createdAt;
}

public class OrderItemDTO {

    private Long skuId;
    private String skuName;
    private Integer quantity;
    private BigDecimal price;
}

错误码：

public enum OrderErrorCode {

    ORDER_NOT_FOUND("ORDER_NOT_FOUND", "订单不存在"),
    ORDER_ACCESS_DENIED("ORDER_ACCESS_DENIED", "无权访问该订单"),
    ORDER_STATUS_INVALID("ORDER_STATUS_INVALID", "订单状态异常");

    private final String code;
    private final String message;
}

如果手写文档，至少要整理：

接口路径；
请求方法；
路径参数；
查询参数；
响应结构；
字段说明；
错误码；
示例请求；
示例响应；
注意事项。

这部分正好可以交给 AI 生成初稿。

第一步：让 AI 从代码中提取接口结构

不要直接说“帮我写接口文档”，建议先让 AI 做结构提取。

示例 Prompt：

你是一名后端开发工程师，请根据下面的 Spring Boot Controller、DTO 和错误码枚举，提取接口文档所需的信息。

目标：
先提取结构，不要扩展业务规则。

输入内容：
1. Controller 代码
2. DTO 代码
3. 错误码枚举

请按以下格式输出：
- 接口名称
- 请求方法
- 请求路径
- 路径参数
- 查询参数
- 响应字段
- 错误码
- 需要人工确认的问题

要求：
1. 如果字段含义无法从代码判断，请标注“需要确认”；
2. 不要编造权限规则；
3. 不要假设 status 的可选值；
4. 输出使用 Markdown 表格。

这个 Prompt 的重点是限制模型不要自行发挥。接口文档最怕“看起来完整但事实错误”。

第二步：生成 Markdown 文档初稿

在结构提取确认后，再让 AI 生成完整文档。

请基于上一步提取的信息，生成一份 Markdown 接口文档初稿。

文档结构如下：
1. 接口说明
2. 请求方式
3. 请求参数
4. 响应参数
5. 成功响应示例
6. 错误码
7. 调用说明
8. 需要确认的问题

约束：
- 不要新增代码中没有出现的字段；
- 对不确定的业务含义标注“待确认”；
- 示例 JSON 中字段要和 DTO 保持一致；
- 错误码只能使用我提供的枚举；
- 文风简洁，适合放入项目 Wiki。

AI 可能生成如下文档初稿。

接口说明

查询订单详情。

请求方式

GET /api/orders/{orderId}

请求参数

参数名	位置	类型	是否必填	说明
orderId	Path	Long	是	订单 ID
includeItems	Query	Boolean	否	是否返回订单明细，具体行为待确认

响应参数

字段名	类型	说明
orderId	Long	订单 ID
orderNo	String	订单编号
status	String	订单状态，取值范围待确认
totalAmount	BigDecimal	订单总金额
currency	String	币种
items	Array	订单明细列表
createdAt	LocalDateTime	创建时间

订单明细字段

字段名	类型	说明
skuId	Long	商品 SKU ID
skuName	String	商品名称
quantity	Integer	数量
price	BigDecimal	单价

成功响应示例

{
  "code": "OK",
  "message": "success",
  "data": {
    "orderId": 10001,
    "orderNo": "ORD202501010001",
    "status": "PAID",
    "totalAmount": 199.00,
    "currency": "CNY",
    "items": [
      {
        "skuId": 20001,
        "skuName": "示例商品",
        "quantity": 1,
        "price": 199.00
      }
    ],
    "createdAt": "2025-01-01T10:00:00"
  }
}

错误码

错误码	说明
ORDER_NOT_FOUND	订单不存在
ORDER_ACCESS_DENIED	无权访问该订单
ORDER_STATUS_INVALID	订单状态异常

这类初稿已经能节省不少时间，但还不能直接发布。

第三步：让 AI 检查文档和代码是否一致

生成文档后，可以继续让 AI 做一次“反向检查”。

请检查下面的接口文档是否与给定的 Controller、DTO、错误码枚举一致。

重点检查：
1. 是否出现代码中不存在的字段；
2. 是否遗漏 DTO 中的字段；
3. 示例 JSON 字段是否与 DTO 一致；
4. 错误码是否存在编造；
5. 是否有不确定但未标注“待确认”的业务规则。

输出格式：
- 不一致项
- 可能遗漏项
- 建议人工确认项
- 可直接修改的文案

这个步骤很实用。AI 在第一次生成时可能会补充一些“合理但不存在”的字段，例如 updatedAt、userId、paymentStatus。反向检查可以减少这类问题。

第四步：从接口文档反推测试点

接口文档不是只给前端看的，也可以反过来帮助测试设计。

示例 Prompt：

请根据下面的接口文档，生成接口测试点草稿。

要求：
1. 按正常场景、异常场景、边界场景分类；
2. 不写具体测试代码；
3. 每个测试点包含输入、预期结果、关注点；
4. 不要假设文档中没有说明的业务规则；
5. 对不确定的地方标注“需要确认”。

可能得到的测试点：

类型	输入	预期结果	关注点
正常场景	存在的 orderId，includeItems=true	返回订单详情和明细	items 是否返回
正常场景	存在的 orderId，includeItems=false	返回订单详情	items 是否为空或不返回需确认
异常场景	不存在的 orderId	返回 ORDER_NOT_FOUND	错误码一致
异常场景	无权限访问订单	返回 ORDER_ACCESS_DENIED	权限校验
边界场景	orderId 非数字	参数校验失败	框架层错误格式
边界场景	includeItems 为空	使用默认行为	默认值需确认

这里可以看到，AI 不只是生成文档，也能帮忙暴露文档里的模糊点，比如 includeItems=false 时 items 字段到底是不返回、返回空数组，还是返回 null。

第五步：把接口变更整理成版本说明

接口文档维护难，往往不是第一次写，而是后续变更没人同步。

可以让 AI 根据 Git diff、变更描述或代码片段生成变更说明：

请根据下面的接口变更内容，生成一段适合放入 CHANGELOG 的说明。

变更内容：
1. OrderDetailDTO 新增字段 refundStatus；
2. getOrderDetail 接口新增 query 参数 includeRefundInfo；
3. 新增错误码 ORDER_REFUND_NOT_FOUND；
4. 老字段 status 语义不变。

要求：
- 输出 Markdown；
- 分为新增、兼容性影响、测试建议；
- 不要夸大影响；
- 如果存在需要确认的兼容性问题，请列出。

输出示例：

### 订单详情接口变更

#### 新增
- `OrderDetailDTO` 新增 `refundStatus` 字段，用于表示订单退款状态。
- `GET /api/orders/{orderId}` 新增 `includeRefundInfo` 查询参数。
- 新增错误码 `ORDER_REFUND_NOT_FOUND`。

#### 兼容性影响
- 原有 `status` 字段语义保持不变。
- `refundStatus` 的默认返回行为需要确认：当未传 `includeRefundInfo` 时是否返回该字段。

#### 测试建议
- 覆盖未传 `includeRefundInfo` 的默认行为。
- 覆盖传入 `includeRefundInfo=true` 时的退款信息返回。
- 覆盖退款信息不存在时的错误码。

这种方式适合配合 PR 使用，降低接口变更遗漏。

如何验证 AI 生成的接口文档

AI 生成技术文档后，建议至少做 6 类检查。

1. 字段检查

逐项对照 DTO、VO、Response 类：

字段是否遗漏；
字段名是否拼错；
类型是否正确；
数组和对象层级是否正确；
是否出现代码中不存在的字段。

2. 参数检查

对照 Controller 或路由定义：

Path 参数是否完整；
Query 参数是否完整；
Body 参数是否准确；
必填规则是否正确；
默认值是否明确。

3. 错误码检查

对照错误码枚举或统一异常定义：

错误码是否真实存在；
message 是否一致；
是否遗漏常见错误；
是否把框架错误和业务错误混在一起。

4. 示例检查

示例 JSON 很容易出错，需要检查：

字段是否和响应结构一致；
数字、字符串、布尔值类型是否正确；
时间格式是否符合项目约定；
空数组、null、不返回字段的处理是否明确。

5. 业务语义检查

这部分必须人工确认：

状态值有哪些；
权限失败返回什么；
数据不存在返回什么；
是否存在部分成功；
是否有幂等性要求；
是否有分页、排序、过滤规则。

6. 兼容性检查

接口文档更新时，还要检查：

是否影响已有调用方；
是否改变字段含义；
是否改变默认行为；
是否需要版本号；
是否需要通知前端、测试或第三方接入方。

多模型 AI 工具如何判断是否适合文档工作流

在接口文档场景里，选择工具不应只看能否生成文字，更应该看是否适合持续维护。

可以从这些角度判断：

是否方便粘贴较长代码和 DTO；
是否支持多轮上下文，便于从结构提取到文档生成；
Markdown 表格和代码块格式是否稳定；
是否方便比较不同模型对同一接口的理解差异；
是否能保存历史会话，便于后续维护；
是否有清晰的数据安全说明；
是否适合团队形成统一 Prompt 模板。

如果只是想对比 ChatGPT、Claude、Gemini、DeepSeek 在同一接口文档任务中的输出差异，可以使用一些多模型聚合工具进行横向比较。但工具本身不是核心，核心仍然是文档规范、校验流程和团队维护习惯。

注意事项：不要把文档外包给 AI

不要输入敏感业务代码

如果项目未开源，不建议直接粘贴大段完整业务代码。更稳妥的方式是提供经过裁剪的 Controller、DTO、错误码和必要业务说明。

不要让 AI 编造字段含义

字段名叫 status，不代表模型知道它有哪些取值。凡是无法从代码判断的内容，都应该标注“待确认”。

不要忽略接口契约

接口文档不是说明书而已，它是前后端、测试、第三方调用方之间的契约。错误文档会直接导致联调成本上升。

不要一次性生成最终版

更可靠的流程是：

结构提取；
文档初稿；
一致性检查；
人工修订；
测试点反推；
PR 或 Wiki 更新。

常见问题

1. AI 能不能直接根据代码生成 OpenAPI 文档？

可以生成草稿，但不建议直接作为最终版本。OpenAPI 对类型、必填、枚举、示例、错误响应都有明确要求，仍需要结合项目规范校对。

2. 接口文档和 Swagger 已经有了，还需要 AI 吗？

Swagger 更擅长描述接口结构，AI 更适合补充业务解释、调用注意事项、变更说明和测试点。两者并不冲突。

3. 如何避免 AI 写出不存在的字段？

Prompt 中明确要求“不要新增代码中没有出现的字段”，并增加反向检查步骤。最终仍要人工对照 DTO。

4. 文档生成后谁来负责维护？

建议由接口负责人维护，AI 只能降低初稿和检查成本。可以在 PR 模板中增加“是否更新接口文档”这一项。

5. 多模型对比在文档场景中有必要吗？

简单接口没必要。复杂接口、历史包袱多的接口、需要对外提供的 API，可以让多个模型分别检查遗漏点，增加可靠性。

一个可复用的接口文档 Prompt 模板

最后整理一个通用模板，适合放到团队 Wiki 中。

你是一名后端开发工程师和技术文档作者，请根据我提供的接口代码生成接口文档初稿。

输入内容：
1. Controller / Router 代码
2. Request DTO
3. Response DTO
4. 错误码定义
5. 必要业务说明

输出结构：
1. 接口说明
2. 请求方式
3. 请求参数
4. 响应参数
5. 成功响应示例
6. 错误响应示例
7. 错误码说明
8. 调用注意事项
9. 需要人工确认的问题
10. 可反推的测试点

约束：
- 不要新增代码中没有出现的字段；
- 不要编造业务规则；
- 无法确认的内容标注“待确认”；
- 示例 JSON 必须与 DTO 字段一致；
- 错误码只能使用我提供的内容；
- 文档风格简洁，适合放入项目 Wiki；
- 输出 Markdown。

这个模板可以根据团队技术栈调整。例如前端项目可以把 Controller 换成接口定义文件，Node.js 项目可以换成 Router 和 Schema，Go 项目可以换成 Handler 和 Response Struct。

总结

AI 辅助接口文档整理，最有价值的不是“自动写一篇漂亮文档”，而是把开发者从重复整理中解放出来，同时帮助发现遗漏：

从代码提取接口结构；
生成 Markdown 文档初稿；
检查字段和示例是否一致；
反推测试点；
整理接口变更说明；
标注需要人工确认的业务规则。

在开发工作流中，ChatGPT、Claude、Gemini、DeepSeek 都可以用于技术文档整理。更稳妥的做法是把 AI 放在“初稿生成”和“检查遗漏”的位置，而不是让它直接决定接口语义。

接口文档最终要服务于协作。只要能让前端少问一次字段含义、测试少漏一个边界场景、后端少返工一次联调问题，AI 在这条链路里就已经发挥了实际价值。