文章摘要：本文探讨了如何利用AI工具（如ChatGPT、Claude、Gemini、DeepSeek）辅助整理旧项目的技术文档。文章指出，旧项目最大的问题往往是文档缺失或过时，而非代码本身无法运行。作者提出了一套可验证的文档整理流程：先让AI提取代码中的结构化信息（接口路径、请求参数、响应字段等），再生成文档初稿，最后由开发者确认业务语义和边界条件。文章对比了不同AI模型在文档整理中的表现差异，并通过SpringBoot接口示例展示了具体操作步骤，包括信息提取、文档生成、反向Review和测试用例补充。最后强调AI生成的内容必须经过人工验证，并提供了文档维护的固化流程和注意事项。

很多旧项目最大的问题不是代码不能跑，而是“没人说得清”。接口字段靠猜，异常码散落在代码里，README 很久没更新，新同事接手时只能一边断点调试一边问人。时间久了，技术债不只体现在代码里，也体现在文档缺失上。

这类工作很适合让 ChatGPT、Claude、Gemini、DeepSeek 这类大模型参与，但重点不是让 AI “凭空写文档”，而是把它放进一套可验证的整理流程里：先读代码和接口，再提取结构化信息，最后由开发者确认业务语义和边界条件。

我自己在对比过自建模型调用流程、开源 UI 工具以及一些多模型聚合产品后，更倾向把它们当成“模型对比实验环境”来使用。例如 KULA（https://ouai.me）这类工具可以在同一任务下切换 Gemini、ChatGPT、Claude、DeepSeek 等模型，适合快速观察不同模型对代码、接口文档和需求描述的理解差异。但工具本身不是重点，真正决定文档质量的，仍然是输入材料是否完整、Prompt 是否清晰，以及后续 Review 是否认真。

一、本文适合谁

这篇文章适合以下几类开发者：

  • 接手旧项目，需要快速理解接口和业务逻辑；
  • 后端开发，需要从 Controller、Service、DTO 中整理接口文档；
  • 前端开发，需要确认接口字段、状态码和异常场景；
  • 测试工程师，需要根据接口文档补充测试用例；
  • 技术负责人，希望减少“只有代码没有文档”的团队问题；
  • 技术作者，需要把零散代码说明整理成可读文档。

本文不会讨论工具访问方式，而是重点分享一套适合 CSDN 技术社区的实践流程：如何用 AI 辅助整理技术文档，并且避免生成不可靠内容。

二、为什么旧项目文档整理很适合 AI 辅助

很多团队的技术文档不是完全没有，而是分散在不同位置：

  • Controller 方法上有一点注释；
  • DTO 字段里有部分校验规则；
  • Service 里写了业务判断；
  • 数据库表字段有简单备注；
  • README 里有过期说明；
  • 测试用例里藏着真实边界条件；
  • 接口异常码可能写在枚举类里。

人工整理当然可以，但非常耗时间。AI 的优势在于可以帮助我们快速完成第一轮归纳：

  1. 从代码中提取接口信息
    例如请求路径、请求方法、参数、响应字段。

  2. 从校验注解中提取约束
    例如必填、长度限制、最大值、最小值。

  3. 从异常处理逻辑中整理错误码
    例如参数错误、无权限、资源不存在。

  4. 从业务逻辑中总结规则
    例如状态流转、权限判断、时间范围限制。

  5. 把零散内容转成 Markdown 文档
    便于团队 Review 和维护。

但这里要强调一点：
AI 可以辅助提取和整理，不能替代开发者确认业务含义。

三、ChatGPT、Claude、Gemini、DeepSeek 在文档整理中的差异

不同模型在技术文档整理场景下的表现并不完全一样，可以按任务来分工。

任务 更适合的模型特点 使用建议
阅读长代码文件 长上下文理解能力强 Claude 通常适合处理较长 Controller、Service 文件
生成接口文档初稿 结构化输出能力强 ChatGPT、DeepSeek 都适合生成 Markdown 表格
解释框架或 API 行为 资料理解和整合能力强 Gemini 适合结合公开技术资料理解框架用法
中文技术说明整理 中文表达自然、代码理解较好 DeepSeek 适合整理中文开发文档
文档润色和归纳 表达稳定、层次清晰 ChatGPT、Claude 适合做最终文档梳理

实际使用时，不建议只问一个模型就结束。更稳妥的方式是：

  • 用一个模型生成文档初稿；
  • 用另一个模型做 Review；
  • 再由开发者逐项核对代码和业务规则。

四、本次示例：从一个 Spring Boot 接口整理文档

假设旧项目里有一个用户查询接口，代码如下。

@RestController
@RequestMapping("/api/users")
public class UserController {

    private final UserService userService;

    public UserController(UserService userService) {
        this.userService = userService;
    }

    @GetMapping
    public ApiResponse<PageResult<UserVO>> listUsers(UserQueryRequest request) {
        PageResult<UserVO> result = userService.listUsers(request);
        return ApiResponse.success(result);
    }
}

请求对象如下：

public class UserQueryRequest {

    private String keyword;

    private String status;

    private Integer pageNum = 1;

    private Integer pageSize = 20;

    public String getKeyword() {
        return keyword;
    }

    public void setKeyword(String keyword) {
        this.keyword = keyword;
    }

    public String getStatus() {
        return status;
    }

    public void setStatus(String status) {
        this.status = status;
    }

    public Integer getPageNum() {
        return pageNum;
    }

    public void setPageNum(Integer pageNum) {
        this.pageNum = pageNum;
    }

    public Integer getPageSize() {
        return pageSize;
    }

    public void setPageSize(Integer pageSize) {
        this.pageSize = pageSize;
    }
}

响应对象如下：

public class UserVO {

    private Long id;

    private String username;

    private String nickname;

    private String status;

    private String createdAt;

    // getter / setter 省略
}

Service 层有部分业务逻辑：

public PageResult<UserVO> listUsers(UserQueryRequest request) {
    if (request.getPageNum() == null || request.getPageNum() < 1) {
        throw new BizException("INVALID_PAGE_NUM", "页码不合法");
    }

    if (request.getPageSize() == null || request.getPageSize() > 100) {
        throw new BizException("INVALID_PAGE_SIZE", "每页数量不合法");
    }

    if (request.getStatus() != null &&
            !List.of("ACTIVE", "DISABLED").contains(request.getStatus())) {
        throw new BizException("INVALID_STATUS", "用户状态不合法");
    }

    return userRepository.queryUsers(request);
}

这段代码信息不复杂，但要整理成文档时，开发者仍然需要关注：

  • 接口路径；
  • 请求方法；
  • 请求参数；
  • 默认值；
  • 参数校验；
  • 状态枚举；
  • 错误码；
  • 响应字段；
  • 分页结构；
  • 待确认问题。

五、第一步：让 AI 提取接口信息

不要一上来就让 AI “写一份完整接口文档”。更合理的做法是先让它提取事实信息。

Prompt 示例：代码信息提取

你是一名后端接口文档整理助手。

请根据下面的 Spring Boot 代码，提取接口事实信息，不要补充代码中不存在的业务规则。

请输出以下内容：

1. 接口路径
2. 请求方法
3. 请求参数
4. 参数默认值
5. 参数校验规则
6. 响应字段
7. 错误码
8. 代码中无法确认、需要人工确认的问题

要求：
- 只基于代码内容总结；
- 不要编造字段含义；
- 如果信息不足，请标记为“待确认”；
- 输出为 Markdown 表格。

代码如下：
粘贴 Controller、Request、VO、Service 代码

这个 Prompt 的关键是强调：只基于代码，不要编造。

因为 AI 在写文档时很容易补充一些“看起来合理”的说明，比如：

  • keyword 支持用户名和手机号；
  • status 支持全部状态；
  • createdAt 使用 ISO 8601 格式；
  • 默认按创建时间倒序。

这些内容如果代码里没有体现，就应该标记为“待确认”，而不是直接写进文档。

六、第二步：生成接口文档初稿

当 AI 提取出事实信息后，再让它生成文档初稿会更可靠。

Prompt 示例：生成 Markdown 接口文档

请基于前面提取出的接口事实信息，生成一份接口文档初稿。

文档结构如下：

1. 接口名称
2. 接口说明
3. 请求方式
4. 请求路径
5. 请求参数表
6. 响应字段表
7. 请求示例
8. 响应示例
9. 错误码说明
10. 待确认问题

要求：
- 使用 Markdown 格式；
- 不要删除“待确认”内容；
- 示例数据必须明显是 mock 数据；
- 不要把推测内容写成确定结论；
- 字段含义不明确时写“待确认”。

生成后的接口文档可能类似下面这样。

七、接口文档示例

1. 接口名称

查询用户列表

2. 接口说明

用于分页查询用户列表。当前代码中可确认支持按 keyword、status、pageNum、pageSize 进行查询。

部分字段具体业务含义需要进一步确认。

3. 请求方式

http

GET /api/users

4. 请求参数

参数名 类型 必填 默认值 说明 校验规则
keyword string 否 无 待确认，可能用于关键词查询 代码中未体现
status string 否 无 用户状态 仅支持 ACTIVE、DISABLED
pageNum integer 否 1 页码 不能为空，且必须大于等于 1
pageSize integer 否 20 每页数量 不能为空，且不能大于 100

5. 响应字段

字段名 类型 说明
id long 用户 ID
username string 用户名
nickname string 用户昵称
status string 用户状态
createdAt string 创建时间，格式待确认

6. 请求示例

http

GET /api/users?keyword=tom&status=ACTIVE&pageNum=1&pageSize=20

7. 响应示例

json

{
  "code": 0,
  "message": "success",
  "data": {
    "total": 1,
    "pageNum": 1,
    "pageSize": 20,
    "list": [
      {
        "id": 10001,
        "username": "tom",
        "nickname": "Tom",
        "status": "ACTIVE",
        "createdAt": "2025-01-01 10:00:00"
      }
    ]
  }
}

8. 错误码说明

错误码 错误信息 触发条件
INVALID_PAGE_NUM 页码不合法 pageNum 为空或小于 1
INVALID_PAGE_SIZE 每页数量不合法 pageSize 为空或大于 100
INVALID_STATUS 用户状态不合法 status 不在 ACTIVE、DISABLED 范围内

9. 待确认问题

问题 说明
keyword 的匹配范围 代码中无法确认是匹配用户名、昵称还是手机号
createdAt 时间格式 VO 中为字符串，但未确认格式
默认排序规则 代码中未体现
pageSize 是否允许小于 1 当前代码只限制了 null 和大于 100，未限制小于 1
status 是否需要支持全部状态 当前代码只允许 ACTIVE、DISABLED

八、第三步：让 AI 反向 Review 文档

生成文档后，不要马上发布到团队知识库。可以让另一个模型做 Review。

Prompt 示例：文档 Review

你是一名后端接口文档 Review 人员。

请检查下面这份接口文档是否存在问题，重点关注：

1. 是否有基于代码无法确认却被写成确定结论的内容；
2. 请求参数说明是否完整；
3. 错误码说明是否准确；
4. 响应示例是否可能误导调用方；
5. 是否遗漏待确认问题；
6. 是否存在不利于前后端联调的表达。

请输出：
- 发现的问题
- 风险说明
- 修改建议
- 是否必须修改

这一轮经常能发现一些细节，例如：

  • 响应示例中的 createdAt 格式可能未确认；
  • pageSize 没有限制小于 1，文档不能写“必须大于等于 1”；
  • keyword 不能直接写“支持用户名模糊搜索”；
  • 错误码触发条件要和代码完全一致；
  • ApiResponse 的外层结构需要确认是否全局统一。

九、第四步：补充测试用例，验证文档是否准确

接口文档不是写完就结束，还需要能被测试用例验证。

可以让 AI 根据文档生成测试点。

Prompt 示例：根据接口文档生成测试用例

你是一名测试工程师。

请根据下面的接口文档生成测试用例清单。

要求覆盖：
1. 正常分页查询；
2. status 合法值；
3. status 非法值；
4. pageNum 为空；
5. pageNum 小于 1；
6. pageSize 为空；
7. pageSize 大于 100；
8. keyword 有值和无值；
9. 返回空列表；
10. 响应字段完整性。

请输出：
- 用例编号
- 测试场景
- 请求参数
- 预期结果
- 优先级
- 是否需要人工确认

可能得到如下结果：

用例编号 测试场景 请求参数 预期结果 优先级 是否需要人工确认
TC001 默认分页查询 无 返回第一页用户列表 P0 否
TC002 查询 ACTIVE 用户 status=ACTIVE 返回 ACTIVE 用户 P0 否
TC003 查询 DISABLED 用户 status=DISABLED 返回 DISABLED 用户 P0 否
TC004 非法 status status=LOCKED 返回 INVALID_STATUS P0 否
TC005 pageNum 小于 1 pageNum=0 返回 INVALID_PAGE_NUM P0 否
TC006 pageSize 大于 100 pageSize=101 返回 INVALID_PAGE_SIZE P0 否
TC007 keyword 查询 keyword=tom 返回匹配结果 P1 是，需要确认匹配范围
TC008 查询结果为空 keyword=not_exist 返回空 list P1 是，需要确认空结果结构
TC009 响应字段检查 正常请求 包含 id、username、nickname、status、createdAt P1 否

这里有一个细节：
AI 生成的测试用例里，凡是涉及业务含义不明确的地方，都应该标记为“需要人工确认”。

十、第五步：把文档维护流程固化下来

如果只是临时让 AI 写一份文档，收益有限。更好的做法是把流程固化到团队日常开发中。

可以采用下面这套流程：

代码变更
  ↓
提取接口信息
  ↓
AI 生成文档初稿
  ↓
AI 辅助 Review
  ↓
开发者人工确认
  ↓
测试补充用例
  ↓
合并到文档仓库

如果团队使用 Git，可以把文档和代码放在同一个仓库里，例如：

project
├── src
│   └── main
│       └── java
├── docs
│   └── api
│       └── user-api.md
└── README.md

这样做的好处是：

  • 接口变更和文档变更可以在同一个 PR 中 Review；
  • 文档不容易长期失效；
  • 测试可以根据文档补充用例；
  • 新同事接手时不需要到处找资料。

十一、如何判断多模型 AI 工具是否适合文档整理

在文档整理场景下，选择工具时不应该只看“能不能聊天”，而要看它是否能支撑稳定的工作流。

可以从下面几个角度判断：

1. 是否支持长文本输入

旧项目代码往往比较长，如果上下文长度太短，需要频繁拆分，会影响整理效率。

2. 是否方便切换模型

同一段代码，不同模型可能会给出不同结论。能方便对比多个模型的输出，有助于发现遗漏点。

3. 是否支持 Markdown 输出

接口文档、测试用例、字段表格都适合用 Markdown 管理。输出格式稳定很重要。

4. 是否便于复制和二次编辑

AI 生成的内容一定要经过人工修改，因此工具不应让编辑成本变高。

5. 是否能保护敏感信息

整理真实项目文档时，必须注意代码和数据脱敏。无论使用哪类工具，都不应输入敏感配置、密钥、生产数据或用户隐私信息。

十二、AI 整理技术文档时的注意事项

1. 不要让 AI 编造业务规则

这是最常见的问题。
如果代码中没有体现“按创建时间倒序”，文档里就不能写成确定规则。

更稳妥的写法是：

默认排序规则：待确认，当前代码片段中未体现。

2. 不要忽略异常场景

很多接口文档只写正常请求和响应，但真实联调最容易出问题的是异常场景：

  • 参数非法；
  • 无权限；
  • 数据不存在；
  • 状态不允许；
  • 分页越界；
  • 返回空列表。

AI 可以帮助补充异常场景，但仍要和代码核对。

3. 不要把示例数据写得像真实数据

示例数据应使用明显的 mock 值，避免出现真实手机号、邮箱、用户 ID、订单号等。

例如：

json

{
  "id": 10001,
  "username": "mock_user",
  "nickname": "测试用户"
}

4. 不要上传敏感代码和配置

不要输入以下内容：

  • 数据库账号密码；
  • API Key；
  • Token；
  • 内部域名；
  • 生产 IP；
  • 用户隐私数据；
  • 未公开业务策略；
  • 安全相关配置。

如果需要分析真实代码，应先做脱敏处理。

5. 不要跳过人工 Review

AI 生成文档看起来很完整，但可能存在事实错误。
尤其是字段含义、业务规则、状态流转、权限逻辑，必须由熟悉项目的人确认。

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

下面这个模板可以直接用于旧项目接口整理。

你是一名后端接口文档整理助手。

请根据我提供的代码，整理接口文档初稿。

目标：
1. 从代码中提取接口路径、请求方法、请求参数、响应字段；
2. 从校验逻辑中提取参数约束；
3. 从异常处理逻辑中提取错误码；
4. 标记代码中无法确认、需要人工确认的问题；
5. 输出适合团队 Review 的 Markdown 文档。

输入内容：
- Controller 代码
- Request DTO 代码
- Response VO 代码
- Service 中相关校验逻辑
- 错误码枚举，如有

输出格式：
1. 接口名称
2. 接口说明
3. 请求方式
4. 请求路径
5. 请求参数表
6. 响应字段表
7. 请求示例
8. 响应示例
9. 错误码说明
10. 待确认问题
11. 建议补充的测试用例

约束：
- 不要编造代码中不存在的业务规则；
- 不确定的内容必须标记为“待确认”；
- 示例数据使用 mock 数据；
- 不要输出敏感信息；
- 不要建议大规模重构代码；
- 输出内容要便于开发、测试、前端共同 Review。

十四、常见误区

1. AI 能不能直接生成准确接口文档？

可以生成初稿，但不能保证完全准确。
接口文档必须和代码、测试用例、业务规则一起核对。

2. 文档整理应该用一个模型还是多个模型？

简单接口用一个模型通常够用。复杂接口、长代码、历史逻辑较多的项目，可以用多个模型交叉检查，减少遗漏。

3. AI 生成的字段说明能直接用吗？

不建议直接使用。
字段说明如果代码中没有明确注释，AI 很可能根据命名进行推测。推测内容应该标记为“待确认”。

4. 旧项目没有注释，AI 还能整理吗？

可以，但准确性会下降。
这时更适合让 AI 做“代码事实提取”和“待确认问题列表”，不要让它直接写成确定文档。

5. 接口文档和测试用例要一起生成吗？

建议一起生成。
文档描述的是接口约定，测试用例负责验证这些约定是否成立。两者结合，才能减少文档失真。

总结

AI 辅助技术文档整理的核心价值，不是让开发者少写几段文字，而是让团队更快把零散信息变成可讨论、可 Review、可维护的文档。

比较实用的流程是：

  1. 先让 AI 提取代码事实；
  2. 再生成接口文档初稿；
  3. 用另一个模型做反向 Review；
  4. 人工确认业务语义；
  5. 根据文档补充测试用例；
  6. 把文档和代码变更放进同一个维护流程。

对于旧项目来说，文档不是一次性补完的，而是持续演进的工程资产。
ChatGPT、Claude、Gemini、DeepSeek 可以帮助我们提升整理效率，但最终的准确性，仍然取决于开发者是否认真验证每一条接口约定。

# 人工智能
Logo
https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

cover

用多模型 AI 辅助代码 Review：以一次前端 React 组件重构为例

avatar AI编程社区
cover

从需求分析到测试用例：用 ChatGPT、Claude、Gemini、DeepSeek 辅助接口开发实践

avatar AI编程社区
cover

Claude Code 深度定制指南：从分层架构到 AI 参谋系统的高级搭建实践

avatar AI编程社区