接口变更总漏写文档？AI接口文档生成提示词一键导出OPENAPI与SWAGGER规范

联调排查发现字段名对不上、类型从整型悄悄变成了字符串、必填字段少传报错 500——这类事故在敏捷迭代团队中几乎每周都在上演。只要业务跑得快，后端工程师重构了 Controller 和 DTO，改完了数据库字段，却总把 Swagger 注解或 Postman 共享文档遗落在脑后。

要彻底解决“代码先行、文档滞后”的问题，靠行政规范和团队考核往往收效甚微。最实用的办法是让文档生成退回到代码提交或代码评审阶段，依托大模型直接从代码变更（Git Diff）或原始 Handler/DTO 中逆向生成标准 OpenAPI/Swagger 规范。

一、 规范选型：别在版本格式上踩坑

在让大模型编写规范之前，必须在提示词中明确目标版本，否则大模型会随机混合不同规范的字段，导致下游解析器直接报错。目前业内主流有三套规范标准：

1.Swagger 2.0（OpenAPI 2.0）：老旧但兼容性广。请求体放在 `parameters` 中使用 `in: body`，根节点使用 `host`、`basePath` 和 `schemes`，组件复用定义在 `definitions`。

2.OpenAPI 3.0：目前企业端落地最普及的版本。引入了独立的 `requestBody` 节点，支持多套 `servers` URL 配置，复用模型移入 `components/schemas`，支持 `nullable: true`。

3.OpenAPI 3.1：完全与 JSON Schema Draft 2020-12 对齐。废弃了 `nullable: true`，统一改为类型数组 `type: [“string”, “null”]`，并支持顶层 `webhooks` 定义。

如果团队内部使用老版 Swagger UI 或旧版脚手架生成客户端 SDK，建议生成 OpenAPI 3.0；如果是新建现代项目或对接 Spectral 规则校验，优先选择 OpenAPI 3.1。

二、 主流大模型实测与参数配置

生成接口文档本质是确定性极强的结构化逆向工程，不能留给模型自由发挥的创作空间。参数配置必须收敛：

•Temperature：设置在 0.0 到 0.1 之间。文档需要绝对精确的字段提取，温度过高会导致模型凭空编造接口字段。

•Top-P：设置在 0.1 到 0.2。配合低温度锁定概率最高的前置 token。

•输出格式首选 YAML：相较于 JSON，YAML 省略了大量的双引号、大括号和逗号，不仅节省 30% 以上的 Context Token，还能大幅减少由于 JSON 尾部逗号错漏引发的解析异常。

不同主流模型在处理复杂嵌套 DTO 和 Git Diff 时的实际表现如下表所示：

三、 生产级通用提示词模板

普通提示词（如“请帮我把这段代码写成 Swagger 文档”）生成的产物往往包含大量废话，字段类型含糊，甚至将公共模型直接内联平铺，导致后续根本无法维护。

设计高质量提示词，需要引入明确的系统角色边界、AST级逆向逻辑、规范版本锁定与纯净格式约束。

1. 增量更新模式：从 Git Diff 生成差异文档补丁

当接口发生微小变动时，不要重新生成整份规范，让模型只分析变更差异，输出对应的 OpenAPI 变更片段：

# Role
你是一名资深 API 架构师与 OpenAPI/Swagger 规范专家。

# Task
阅读开发者提交的代码差异（Git Diff），对比旧逻辑与新逻辑，输出符合 OpenAPI 3.1 规范的接口变动 YAML 片段。

# Rules & Constraints
1. 严格使用 OpenAPI 3.1 规范输出。
2. 零冗余输出：严禁输出任何问候语、操作解释、说明文字或 Markdown 外部导语，仅输出一个合规的 ```yaml 代码块。
3. 字段变更捕获：
   - 如果新增参数，精确标记字段名、类型（与 JSON Schema 2020-12 对齐）、是否必填（required）、以及从代码注释提取的 description。
   - 如果字段可为空，必须声明为 `type: ["string", "null"]`，禁止使用 `nullable: true`。
   - 提取代码中的校验注解（如 @NotNull, @Size, @Pattern, validate:"required" 等），转换为对应的 minimum, maximum, pattern, minLength 规范。
4. 结构拆分：
   - 路径路由定义放在 `paths` 块。
   - 请求/响应体涉及的数据结构，必须抽象成 `$ref: '#/components/schemas/ModelName'`，并在 `components.schemas` 下独立定义，严禁过度深层内联。

# Input Data
[在此粘贴 Git Diff 或包含增删标记的代码片段]

2. 全量源码模式：Controller + DTO 一键生成标准化规范

对于完全没有文档的存量接口或新开发接口，直接提供控制器实现类与相关的传输对象（DTO/Entity），使用以下生产级模板：

# Context & Role
你是一名严格的代码逆向与 API 契约生成引擎。你拥有资深的 API 规范编写经验，熟悉 Spring Boot、Go Gin、FastAPI、NestJS 等主流后端框架。

# Objective
根据提供的后端接口代码与数据结构定义，生成一份结构完整、可直接导入 Swagger Editor / Apifox / Postman 的标准 OpenAPI 3.0.3 YAML 文档。

# Execution Guidelines
1. **基础信息提取**：
   - 依据 Controller 类级别路由与方法路由，拼接完整 path。
   - 依据 HTTP 动作注解（GET/POST/PUT/DELETE/PATCH）确定方法节点。
   - 提取代码行内注释作为 `summary` 和 `description`；若无注释，根据方法名推理生成精炼中文说明。
2. **入参规范化**：
   - 区分 `in: path`、`in: query`、`in: header` 参数。
   - 请求体统一使用 `requestBody.content.application/json.schema`。
   - 识别枚举类（Enum），将其转换为规范中的 `enum` 列表，并在 description 中标注枚举含义。
3. **响应规范化**：
   - 至少定义 `200` 成功响应结构与 `400` / `500` 常见异常响应。
   - 成功响应若为通用包装类（如 Result<T> / ApiResponse<T>），必须保留最外层 `code`, `message`, `data` 结构，将实际业务 DTO 挂载在 `data` 下。
4. **格式控制**：
   - 禁止出现非 YAML 规范的字符。
   - 缩进严格遵循 2 个空格。
   - 纯净输出，禁止包裹任何聊天废话。

# Source Code
[在此粘贴 Controller 源码及涉及的 DTO / Model 定义]

四、 提示词优化前后对比

为了直观观察提示词工程的效果，以一个常见的“修改用户信息”Spring Boot 接口为例，观察模型在不同提示词驱动下的表现差异：

五、 落地全流程 SOP：从代码提取到 CI/CD 自动化校验

仅在聊天窗口粘贴代码并不是最高效的工程实践。建议将上述提示词固化为团队标准的协作流程：

[Git 代码提交/PR] 
       │
       ▼
[提取变更 Git Diff / 源码片段] 
       │
       ▼
[调用大模型 API (Temperature=0.0)] 
       │
       ▼
[Spectral 规范语法与合规性校验] ──(校验不通过)──> [告警中断/重新解析]
       │ (校验通过)
       ▼
[自动推送到 Swagger UI / Apifox / 契约仓库]

Step 1: 提取目标接口上下文

编写自动化脚本（如 Python 或 Shell）提取待评审的变更。注意：不要盲目打包整个工程，只提取 Controller 和相关的 DTO/POJO 文件。超大无用上下文会稀释注意力，增加模型的幻觉概率。

Step 2: 规范语法自动化静态校验（Linting）

大模型即使表现优异，偶发性的缩进错误或拼写失误仍在所难免。在将生成的 YAML 归档前，必须通过工具进行校验。推荐在 CI 流程中使用开源工具 Spectral：

# 安装 Spectral CLI
npm install -g @stoplight/spectral-cli

# 校验模型生成的 openapi.yaml 是否符合官方规则集
spectral lint openapi.yaml --ruleset https://raw.githubusercontent.com/stoplight/spectral/develop/packages/rulesets/src/oas/index.ts

如果校验命令报错，直接将 Spectral 返回的具体行号与 Error 信息回传给大模型进行自我纠错（Self-Correction），通常一次重试即可恢复正确结构。

Step 3: 自动化导入工具链

通过 OpenAPI 规范的标准化格式，可以直接借助自动化 API 将生成的 YAML 推送到现有平台（如 Swagger UI 静态目录、Apifox 开放 API、Postman Collection 或 Git 契约库），完成文档与代码的无缝同步。

六、 核心避坑指南与边界防御

在实际落地过程中，有几个隐蔽陷阱需要特别防范：

1.类型声明中的 Nullable 陷阱

很多开发者在指定 OpenAPI 3.1 时，大模型依然习惯性输出 `nullable: true`。这在 3.1 中属于非法字段。必须在 System Prompt 中强制加入负向约束：`在 OpenAPI 3.1 下严禁使用 nullable: true，必须使用 type: [“string”, “null”] 数组形式`。

2.嵌套循环引用（Circular Dependency）

在 ORM 映射模型中，经常出现 `User` 包含 `Order`，而 `Order` 又反向包含 `User` 的情况。如果不加限制，大模型会陷入死循环递归展开，最终导致 Token 溢出耗尽。解决方案：在提示词中显式约束“遇到父子双向关联字段时，子对象只保留 ID 或使用浅层模型，禁止深度递归”。

3.安全鉴权方案（Security Schemes）配置

接口通常伴随 Header 中的 JWT Token 或 API Key。如果不在提示词中约束，模型会针对每个接口都单独写一遍 `Authorization` Header 参数。正确做法：要求模型在根节点声明 `components.securitySchemes`（如 `bearerAuth`），然后在具体接口路由下挂载 `security: [{ bearerAuth: [] }]`。

4.枚举类的注释映射

后端代码中的 Enum 往往只有数字（如 `0`, `1`, `2`）或大写字符串（`PENDING`, `SUCCESS`）。一定要在提示词中提醒：“将枚举定义的中文说明附加至对应属性的 `description` 中，形如 `状态码：0-未开始, 1-进行中, 2-已完成`”，避免前端联调时反复核对字典含义。