一次旧接口文档整理的 AI 辅助流程：从上下文至验收

最近帮一个老项目补接口文档，过程不算复杂，但很典型：代码能跑，接口也有人在用，文档却停在两年前。新人接手时只能翻 Controller、看前端调用、问老同事，遇到参数含义还得去数据库里猜。

这类任务很适合让 AI 参与，但不适合直接丢一句“帮我生成接口文档”。我试过，结果通常看起来很完整，实际上有不少细节是模型自己补的：字段含义不准、错误码编造、权限说明缺失，甚至把旧接口理解成了新接口。

后来我把流程改成了“让 AI 做中间环节”，效果稳定很多。本文记录一下这套比较低风险的做法，适合后端开发、测试工程师、技术文档维护者参考。

为什么旧接口文档适合 AI 辅助，但不能全交给 AI

旧接口文档整理有几个特点：

• 信息分散在代码、注释、调用方、数据库字段、历史需求里；
• 很多接口逻辑不难，但分支多；
• 文档结果可验证，可以用代码、测试、日志反查；
• 输出格式相对固定，适合结构化生成。

这正好符合 AI 比较擅长的部分：阅读、归纳、转换格式、发现遗漏。

但它也有明显风险：

• AI 不知道你们公司的真实业务约定；
• 代码里没有写出的隐性规则，模型无法凭空知道；
• 如果上下文太长，模型可能忽略关键分支；
• 生成的错误码、权限规则、字段解释，看起来合理但未必真实。

所以我现在的原则是：不要让 AI 直接“写最终文档”，而是让它先做结构化提取、问题清单和初稿，再由人验收。

我一般会把任务拆成 5 步

1. 先准备可控上下文，而不是整包代码乱丢

不要一上来就把整个项目复制进去。对于一个接口，我通常只准备这些材料：

1. Controller 或 Router 中对应方法；
2. DTO / VO / Request / Response 类；
3. Service 中与该接口直接相关的核心逻辑；
4. 枚举类、错误码定义；
5. 权限注解、网关配置或拦截器说明；
6. 一两条脱敏后的真实请求和响应样例。

如果涉及公司内部字段、用户信息、订单号、手机号、Token、日志 Trace 等，一定先脱敏。测试环境数据也不要直接当成“安全数据”，很多测试库里照样有真实信息。

我会把上下文整理成这种格式：

背景：
这是一个 Java Spring Boot 项目中的订单查询接口，用于后台运营系统。

接口代码：
[粘贴 Controller 方法]

请求对象：
[粘贴 Request DTO]

响应对象：
[粘贴 Response VO]

核心业务逻辑：
[粘贴 Service 相关方法，不包含无关代码]

错误码：
[粘贴枚举或说明]

已知限制：
- 只整理文档，不修改代码
- 不允许编造数据库字段
- 不确定的内容必须标记为“待确认”

这里的关键不是“给得越多越好”，而是“给得足够且边界清楚”。

2. 第一轮只让 AI 提取事实，不让它润色

我会先让模型做事实抽取，而不是直接写文档。

可用 Prompt：

你是一名后端接口文档整理助手。请只基于我提供的代码和说明，提取接口事实信息。

要求：
1. 不要补充代码中没有体现的信息；
2. 不确定的地方用【待确认】标记；
3. 按以下结构输出：
   - 接口用途
   - 请求方法与路径
   - 权限要求
   - 请求参数表
   - 响应字段表
   - 主要业务流程
   - 错误码与触发条件
   - 需要人工确认的问题清单

请不要写营销化或教程化语言。

这一轮的目标很简单：把散落的信息收拢起来。

如果模型输出里出现“显然”“通常”“可能会”这类词，我会特别留意。技术文档里这些词经常意味着它在猜。

3. 第二轮让 AI 生成文档初稿，但保留“待确认项”

事实提取确认后，再让它生成文档初稿。

请基于上一轮提取结果，生成一份面向前端开发和测试工程师的接口文档初稿。

格式要求：
1. 使用 Markdown；
2. 参数表包含：字段名、类型、是否必填、含义、示例、备注；
3. 响应表包含：字段名、类型、含义、备注；
4. 错误码单独成表；
5. “待确认”内容不得删除，统一放到文档末尾；
6. 不要改变接口语义。

这一步 AI 的价值主要在排版和结构化，不是替你判断业务。

我比较喜欢让它保留“待确认项”，因为这能把文档整理变成一个可协作的流程：后端、前端、测试、产品可以围绕这些点补齐信息，而不是在一篇看起来完美的文档里找问题。

4. 用另一个模型做交叉审查，而不是相信第一版

如果任务比较重要，我会用另一个模型再审一遍。不同模型的风格差异挺明显：

• ChatGPT 通常结构化能力比较稳，适合生成清晰文档和改写；
• Claude 对长上下文和需求类材料比较友好，适合找逻辑遗漏；
• Gemini 在结合表格、长文本摘要时体验不错；
• DeepSeek 对代码语义和中文技术表达比较实用；
• Grok 偶尔能给出不同角度的问题，但仍要人工核对。

这里不是说谁一定更强，而是同一份材料换一个模型看，容易暴露第一版没有发现的问题。

审查 Prompt 可以这样写：

请你作为接口文档 Review 人员，检查下面这份文档是否与代码上下文一致。

请重点检查：
1. 是否存在代码中没有体现、但文档写成确定事实的内容；
2. 请求参数是否遗漏必填、默认值、枚举范围；
3. 响应字段是否与返回对象一致；
4. 错误码和触发条件是否对应；
5. 权限、分页、排序、时间范围等边界条件是否遗漏；
6. 哪些内容需要人工确认。

输出格式：
- 高风险问题
- 中风险问题
- 表达优化建议
- 待人工确认清单

这一步很重要。很多时候，第二个模型不会直接告诉你“这里错了”，但它会问出好问题，比如：

• status 字段到底是订单状态还是审核状态？
• 空列表返回 [] 还是 null？
• 时间字段单位是秒还是毫秒？
• 分页页码从 0 开始还是从 1 开始？
• 权限失败返回 401 还是业务错误码？

这些问题都很值得人工确认。

5. 最后一定要做人工验收

AI 生成文档后，我通常会按下面几项验收：

如果时间允许，我还会让测试同事基于文档反向生成几条测试用例，再跑一遍接口。文档能不能指导测试，是判断它是否靠谱的好方法。

一个更贴近开发现场的例子

假设有个接口：

@GetMapping("/api/orders")
public PageResult<OrderVO> listOrders(OrderQueryRequest request) {
    return orderService.listOrders(request);
}

请求对象里有：

public class OrderQueryRequest {
    private String keyword;
    private Integer status;
    private Long startTime;
    private Long endTime;
    private Integer pageNo = 1;
    private Integer pageSize = 20;
}

Service 里又有：

if (request.getPageSize() > 100) {
    request.setPageSize(100);
}
if (request.getStartTime() != null && request.getEndTime() != null
        && request.getStartTime() > request.getEndTime()) {
    throw new BizException(ErrorCode.INVALID_TIME_RANGE);
}

如果直接让 AI 写文档，它可能只会生成普通参数表。但通过事实提取，它更容易抓到几个关键点：

• pageNo 默认值为 1；
• pageSize 默认 20，最大 100；
• startTime 不能大于 endTime；
• status 需要结合枚举确认；
• keyword 具体匹配订单号、用户名还是手机号，需要看查询条件或人工确认。

这些细节才是旧接口文档最容易缺失的部分。

AI 更适合做哪些低风险任务

在接口文档整理这件事上，我更愿意把下面这些工作交给 AI：

• 从代码中提取参数和响应字段；
• 把零散注释整理成表格；
• 根据已有错误码生成说明草稿；
• 从接口逻辑中提炼边界条件；
• 帮忙列出待确认问题；
• 根据文档草稿生成测试点；
• 把长文档改成更易读的版本。

但下面这些我不会直接交给 AI 决定：

• 字段最终业务含义；
• 权限规则；
• 金额、状态、结算类逻辑；
• 合规、风控、审计相关说明；
• 对外开放接口的最终描述；
• 是否删除或修改历史兼容行为。

一句话：能验证的让 AI 提效，不能验证的让人拍板。

多模型怎么选，不必纠结“哪个最好”

开发者很容易陷入一个误区：总想找一个“最适合所有任务”的模型。实际用下来，我更建议按任务拆：

• 代码片段理解：看它是否能指出真实分支和边界；
• 长文档整理：看它是否能保持前后字段一致；
• 需求拆解：看它是否会主动暴露不确定项；
• 测试用例生成：看它是否覆盖异常路径；
• 中文技术表达：看它写出来是否像团队内部文档，而不是产品宣传稿。

如果你使用的是多模型工具，判断标准也类似：是否方便切换模型、是否支持长上下文、是否能保存会话、是否方便复制结构化结果、是否有基本的数据安全说明。不要只看模型名字，更要看它能不能嵌入你的实际流程。

常见误区

1. 直接粘一大段代码让 AI 写文档，可以吗？

可以，但效果不稳定。更推荐按接口拆上下文，并明确哪些是代码、哪些是背景、哪些是限制条件。上下文越乱，模型越容易忽略关键逻辑。

2. AI 生成的字段说明看起来很合理，还需要确认吗？

需要。尤其是业务字段，比如 type、source、status、scene。这些字段在不同系统里含义差别很大，不能只靠字段名猜。

3. 能不能让 AI 顺便生成测试用例？

可以，而且很有价值。但测试用例必须和真实代码、接口返回、异常处理对齐。AI 适合生成测试点清单，不适合直接替代测试验证。

4. 文档整理是否一定要用多个模型？

不一定。普通内部接口，一个模型加人工 Review 就够了。涉及外部开放接口、支付、权限、风控、合规等场景，再考虑多模型交叉审查。

5. 代码和日志能不能直接发给 AI？

不建议。至少要做脱敏处理，去掉用户信息、密钥、Token、内部域名、订单号、手机号、身份证、真实日志 Trace 等敏感内容。涉及公司核心业务逻辑时，还要遵守团队安全规范。

最后：从一个小接口开始

AI 辅助开发不一定非要从复杂 Agent、自动写代码开始。对很多团队来说，旧接口文档、测试点整理、需求澄清、Bug 复盘，反而是更容易落地的切入点。

我的建议是：先选一个高频、低风险、可验证的任务；把输入上下文整理清楚；用 Prompt 约束模型只基于事实输出；再通过代码、测试、日志和人工 Review 验收结果。

不要把 AI 当最终负责人。让它帮你读材料、列问题、整理结构、生成初稿，这些已经能省下不少时间。真正关键的业务判断，还是要留给开发者自己。