很多后端项目的接口文档，不是没有，而是“散”。一部分在接口平台，一部分在 README，一部分在飞书文档，还有一些只存在于代码注释和测试用例里。等到前端联调、测试补用例、第三方系统接入时，大家才发现字段含义不一致、错误码缺失、示例请求过期，最后还是回头翻 Controller 和日志。

我最近处理过一次类似问题：一个内部订单服务要对外提供部分查询能力，历史接口已经跑了两年，但文档质量一般。直接让 ChatGPT、Claude、Gemini、DeepSeek 或 Grok “帮我写接口文档”，结果通常很漂亮，却不一定可信。更稳的做法是：先让 AI 做缺口分析，再让它生成 OpenAPI 草稿，最后用代码和测试反向校验。

这篇文章不讨论“哪个模型最好”，而是记录一个可复用流程：把零散接口资料整理成可维护的 OpenAPI 文档，并尽量减少 AI 编造字段、误解业务规则的问题。

场景：订单查询接口文档长期没人维护

假设项目里有这样一个 Spring Boot 接口：

java

@RestController@RequestMapping("/api/orders")public class OrderQueryController {
    @GetMapping("/{orderId}")    public OrderDetailResponse getOrderDetail(            @PathVariable String orderId,            @RequestHeader("X-User-Id") String userId,            @RequestParam(required = false, defaultValue = "false") boolean includeItems    ) {        return orderQueryService.getOrderDetail(orderId, userId, includeItems);    }}

响应对象大概是这样：

java

public class OrderDetailResponse {    private String orderId;    private String status;    private BigDecimal totalAmount;    private BigDecimal payAmount;    private List<OrderItemDTO> items;    private LocalDateTime createdAt;}
public class OrderItemDTO {    private String skuId;    private String skuName;    private Integer quantity;    private BigDecimal price;}

历史文档里只有一句：

text

GET /api/orders/{orderId}查询订单详情，支持传 includeItems 返回商品明细。

这显然不够。缺少鉴权说明、请求头、字段枚举、错误码、金额单位、时间格式、items 为空时的语义，也没有示例。

第一步：不要直接写文档，先让 AI 找缺口

我的第一个 Prompt 通常比较克制：

text

你是后端接口文档审阅助手。请根据下面的 Controller、DTO 和历史说明，做接口文档缺口分析。
要求：1. 不要直接生成完整接口文档；2. 列出已明确的信息；3. 列出不明确但必须确认的信息；4. 标记哪些信息不能从代码中推断；5. 不要编造业务规则；6. 输出 Markdown 表格。
资料如下：【粘贴 Controller、DTO、历史文档】

比较理想的输出会类似这样：

类型	内容	是否可从资料确认	备注
请求方法	GET	是	来自 Controller
路径	/api/orders/{orderId}	是	来自 RequestMapping
请求头	X-User-Id	是	是否必填需确认鉴权策略
查询参数	includeItems	是	默认 false
status 枚举	未说明	否	需确认订单状态取值
金额单位	未说明	否	需确认元/分
时间格式	LocalDateTime	部分确认	需确认序列化格式和时区
错误码	未说明	否	需从异常处理或接口规范补充

这一步看似慢，实际能节省很多返工。AI 最容易犯的错误，是把“常见做法”当成“项目事实”。比如它可能默认金额单位是元，默认时间是 UTC，默认没有权限时返回 403，但这些都必须由项目规则确认。

第二步：补齐上下文，而不是反复追问“再完善点”

拿到缺口列表后，需要补资料。可以从几个地方找：

• 全局异常处理类；
• 统一响应包装对象；
• Swagger 注解或旧接口平台；
• 前端调用代码；
• 自动化测试用例；
• 网关鉴权说明；
• 数据库字段备注；
• 历史联调问题记录。

比如补充这些确认信息：

text

补充规则：1. 接口返回统一包装：{ code, message, data }；2. code=0 表示成功；3. 订单不存在返回 ORDER_NOT_FOUND；4. 当前用户无权访问订单返回 ORDER_ACCESS_DENIED；5. status 枚举：CREATED、PAID、SHIPPED、FINISHED、CLOSED；6. 金额单位为元，保留两位小数；7. 时间格式为 yyyy-MM-dd HH:mm:ss，时区为 Asia/Shanghai；8. includeItems=false 时，items 字段返回空数组，不返回 null。

然后再让 AI 生成 OpenAPI 草稿：

text

请根据“接口代码 + DTO + 历史说明 + 补充规则”，生成 OpenAPI 3.0 YAML 草稿。
限制：1. 只使用资料中已确认的信息；2. 未确认内容不要写入 schema；3. 参数、响应字段、错误码都要有 description；4. 金额字段标注单位和格式；5. 时间字段说明格式和时区；6. 输出 YAML，不要解释。

生成结果可以像这样：

yaml

openapi: 3.0.3info:  title: Order Query API  version: 1.0.0
paths:  /api/orders/{orderId}:    get:      summary: 查询订单详情      operationId: getOrderDetail      parameters:        - name: orderId          in: path          required: true          description: 订单 ID          schema:            type: string        - name: X-User-Id          in: header          required: true          description: 当前登录用户 ID          schema:            type: string        - name: includeItems          in: query          required: false          description: 是否返回商品明细，默认为 false          schema:            type: boolean            default: false      responses:        "200":          description: 查询成功          content:            application/json:              schema:                $ref: "#/components/schemas/OrderDetailResult"        "404":          description: 订单不存在        "403":          description: 当前用户无权访问该订单
components:  schemas:    OrderDetailResult:      type: object      required:        - code        - message        - data      properties:        code:          type: integer          description: 业务状态码，0 表示成功          example: 0        message:          type: string          description: 响应消息          example: success        data:          $ref: "#/components/schemas/OrderDetailResponse"
    OrderDetailResponse:      type: object      properties:        orderId:          type: string          description: 订单 ID        status:          type: string          description: 订单状态          enum:            - CREATED            - PAID            - SHIPPED            - FINISHED            - CLOSED        totalAmount:          type: string          format: decimal          description: 订单总金额，单位：元，保留两位小数          example: "129.90"        payAmount:          type: string          format: decimal          description: 实付金额，单位：元，保留两位小数          example: "99.90"        items:          type: array          description: 商品明细；includeItems=false 时返回空数组          items:            $ref: "#/components/schemas/OrderItem"        createdAt:          type: string          description: 创建时间，格式 yyyy-MM-dd HH:mm:ss，时区 Asia/Shanghai          example: "2026-01-07 10:30:00"
    OrderItem:      type: object      properties:        skuId:          type: string          description: 商品 SKU ID        skuName:          type: string          description: 商品名称        quantity:          type: integer          description: 购买数量        price:          type: string          format: decimal          description: 商品单价，单位：元，保留两位小数

注意，这仍然只是草稿。AI 生成 YAML 时，最常见的问题是把业务错误码和 HTTP 状态码混在一起。你的项目如果所有异常都返回 HTTP 200，再通过 code 表达业务错误，就不能照搬上面的 403、404 写法。

第三步：用脚本做文档结构校验

CSDN 读者大多不满足于“看起来没问题”。文档至少要能被工具解析。

可以用 Node.js 简单校验一下：

bash

npm install @apidevtools/swagger-parser

写一个校验脚本：

js

const SwaggerParser = require("@apidevtools/swagger-parser");
async function validate() {  try {    const api = await SwaggerParser.validate("./openapi.yaml");    console.log("OpenAPI 文档结构合法：", api.info.title);  } catch (err) {    console.error("OpenAPI 校验失败：");    console.error(err.message);    process.exit(1);  }}
validate();

再把它放到 CI 里：

yaml

name: validate-openapi
on:  pull_request:    paths:      - "docs/openapi.yaml"
jobs:  validate:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v4      - uses: actions/setup-node@v4        with:          node-version: 20      - run: npm install @apidevtools/swagger-parser      - run: node scripts/validate-openapi.js

这个校验只能保证格式合法，不能保证业务正确。但它能挡住缩进错误、引用错误、schema 写错位置这类低级问题。

第四步：让 AI 反向生成检查清单

生成文档后，我会再开一个新会话，让 AI 站在 Reviewer 角度挑毛病。新会话的好处是减少“顺着上文自我确认”的倾向。

Prompt：

text

你是接口文档 Review 人员。请检查下面的 OpenAPI 文档是否存在风险。
重点检查：1. 字段是否缺少 description；2. 请求参数是否缺少 required/default；3. enum 是否缺少说明；4. 错误响应是否和统一返回结构冲突；5. 示例值是否可能误导调用方；6. 哪些内容需要回到代码或测试确认。
只输出问题清单，不要重写文档。

这一步经常能发现一些细节，比如：

• totalAmount 和 payAmount 用 string 还是 number，需要团队统一；
• items 是否永远非 null，要有序列化测试证明；
• X-User-Id 是否应该由网关注入，而不是调用方传入；
• 错误码到底放在 HTTP status，还是响应体 code。

不同模型在这个流程里的分工

实际使用中，我不会指望一个模型从头包到尾。

模型	更适合的环节	注意点
Claude	长文档、历史需求、接口说明归纳	输出偏完整，要防止把猜测写成事实
ChatGPT	OpenAPI 草稿、脚本、示例请求生成	代码可读性较好，但要跑工具校验
Gemini	多份资料合并、表格化缺口分析	适合整理，但要核对字段细节
DeepSeek	中文业务规则解释、接口语义梳理	对中文上下文友好，仍需代码确认
Grok	从调用方视角提风险点	适合补充边界，但不一定贴合项目规范
ChatGPT Image 2.0	生成接口流程图、技术配图	需要检查版权、品牌规范和信息准确性
Seedance 2.0	做接口联调流程短视频或培训分镜	视频发布前要人工审核和脱敏

多模型对比的价值，不是让它们投票，而是暴露盲区。一个模型没提到的字段歧义，另一个模型可能会指出来。

多模型工具怎么判断是否适合开发流程

如果团队准备把多模型 AI 工具放进研发流程，我建议看几个实际指标：

1. 是否支持同一 Prompt 快速切换模型：方便比较输出差异；
2. 是否便于保存上下文和结果：接口文档、测试用例、Review 记录都需要追溯；
3. 是否能处理长文本：PRD、代码片段、旧文档往往很长；
4. 是否支持多模态任务：技术图解、流程图、培训视频有时也会进入文档体系；
5. 是否方便做安全边界管理：公司代码、日志、客户数据必须脱敏。

工具只是效率层，真正决定质量的是输入材料、Review 机制和验证流程。

风险边界：哪些内容不要直接交给 AI

接口文档整理看起来风险不高，但仍然要注意：

• 不要直接粘贴生产用户数据、真实手机号、订单号、Token；
• 内部域名、密钥、签名算法、网关规则要按公司规范处理；
• AI 生成的错误码、字段枚举必须回到代码或规范确认；
• 文档示例不能暴露真实客户信息；
• 图像、视频素材如果用于公开发布，要检查版权、肖像、商标和平台规则；
• AI 生成代码或脚本，至少要在本地和 CI 中跑一遍。

我个人的原则是：AI 可以参与“整理、归纳、生成草稿、提出问题”，但不能成为接口事实的唯一来源。

FAQ：几个常见误区

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

不建议。代码只能说明一部分事实，比如路径、参数、DTO 字段。鉴权逻辑、错误码、字段语义、金额单位、时间格式、兼容策略，很多都不在 Controller 里。更好的方式是先生成草稿，再由开发、测试、产品共同确认。

2. 单一模型够不够？

简单接口够用。复杂接口，尤其涉及订单、支付、权限、库存这类业务，我更倾向至少用两个模型交叉检查。不是为了比较谁更聪明，而是为了发现遗漏点。

3. Prompt 怎么写更稳定？

少写“帮我完善一下”，多写输入范围、输出格式和禁止项。例如明确要求“不要编造未确认规则”“只输出缺口分析”“用 Markdown 表格”。约束越清楚，后续人工 Review 越省力。

4. 公司代码和日志能直接发给 AI 吗？

不要直接发。至少要做脱敏处理：去掉密钥、Token、真实用户信息、内部域名、订单号、手机号、邮箱等。涉及公司安全规范的内容，应优先使用企业批准的工具和流程。

总结：从可验证的小任务开始

把 AI 用在接口文档整理里，最稳的切入点不是“自动生成完整文档”，而是“找缺口、列问题、生成草稿、辅助 Review”。

我的建议是：

• 先选一个高频、低风险、可验证的接口；
• 输入 Controller、DTO、旧文档和补充规则；
• 让 AI 先做缺口分析，再生成 OpenAPI；
• 用脚本校验结构，用代码和测试校验事实；
• 重要接口用多模型交叉检查；
• 对外发布前做安全、隐私和业务审核。

这样用 AI，速度会快一些，但不会把质量完全交出去。对于接口文档这种长期维护成本很高的东西，这种“半自动、可验证”的方式反而更容易坚持。