API文档手写耗时费力？掌握API接口文档生成提示词一键输出OPENAPI与SWAGGER规范

做后端研发或架构设计的朋友，大概率都经历过手写 API 文档的痛苦。一个中型项目几十上百个接口，手敲 YAML 或 JSON 格式的 OpenAPI 规范，不仅容易出现缩进层级错乱，还会因为漏写字段类型、遗漏错误码定义，导致前后端联调扯皮。更难受的是业务代码频繁变动，手动同步文档几乎注定会滞后。

很多团队尝试直接把 Controller 代码扔给 ChatGPT 或 Claude：“帮我把这段代码转成 Swagger 文档”。结果往往不尽如人意：大模型经常把所有对象全嵌在 `paths` 路径下，导致文档膨胀数千行；漏掉 `@Valid`、`@NotNull` 等校验规则；甚至自己编造出不存在的 HTTP 状态码。

要把大模型转变为精准的 API 文档生成引擎，核心在于用结构化的系统提示词建立契约约束，并配合确定性的采样参数与适配的模型选型。

主流大模型特性分析与推理参数配置

不同大模型在处理结构化接口定义时，底层的代码理解能力与输出稳定性差异明显。直接看一下主流模型的实测表现：

关键参数配置指南

生成 API 规范属于确定性工程任务，不需要模型发挥发散思维。严禁使用对话场景默认的参数：

•Temperature（温度）：必须设置为 0.0 至 0.1。设为 0 能最大程度抑制模型自由发挥，避免凭空捏造字段名与类型。

•Top-P（核采样）：建议固定为 0.1 或保持与极低温度匹配。

•Max Tokens（最大输出限制）：建议设为 4096 或 8192。OpenAPI 文档包含大量属性定义与示例数据，Token 消耗量极大，过小的阈值会导致 YAML/JSON 在结尾处截断，引发解析器语法报错。

•输出格式选择：优先选择 YAML 或配合大模型 JSON Mode。YAML 在 Token 占用上比 JSON 节省约 30% 到 40%，能容纳更多接口；但如果你的下游工具链需要程序强解析，建议直接开启模型的 JSON Mode 输出合法 JSON。

工业级 OpenAPI 3.0 生成提示词框架

要让大模型稳定输出生产可用的规范，提示词必须覆盖四大维度：规范版本锁定、组件复用要求、校验规则映射以及异常分支完备性。

注意看下面的提示词架构，特别规避了版本兼容坑：目前很多主流 Swagger UI（如 3.x/4.x 系列）以及前端代码生成工具（如 openapi-generator）对 OpenAPI 3.1.0 的某些特性（例如 `type: [“string”, “null”]`）支持并不完善。因此，在生产环境中优先指定生成 OpenAPI 3.0.3 规范。

核心 Prompt 模板

# 角色
你是一位拥有十余年经验的资深后端架构师与 API 规范专家，精通 RESTful 架构设计原则与 OpenAPI Specification (OAS) 3.0.3 标准。

# 任务目标
分析用户提供的后端控制器代码（Controller）、数据传输对象（DTO/VO/Entity）或路由定义，逆向推导并输出完全符合 OpenAPI 3.0.3 规范的文档内容。

# 核心约束准则
1. **规范版本**：必须且仅使用 `openapi: 3.0.3`。
2. **格式要求**：只输出合法的标准 YAML 代码块，不要包含任何前导说明、引言或后置总结。
3. **架构解耦（强制）**：
   - 禁止在 `paths` 内部直接内联定义复杂的请求体或响应体对象。
   - 所有通用数据模型、请求参数体、统一响应结构必须抽取至 `components/schemas` 中。
   - `paths` 中必须使用 `$ref: '#/components/schemas/模型名称'` 进行引用。
4. **校验规则推导**：
   - 提取代码中的验证注解（如 Java Bean Validation、TypeScript 类型约束、Pydantic 校验）。
   - 将 `@NotBlank`、`@NotNull` 映射为 `required: true` 或 schema 内的 `required` 列表。
   - 将 `@Size(min, max)`、`@Min`、`@Max` 映射为 `minLength`、`maxLength`、`minimum`、`maximum`。
   - 将枚举类型转换为 `type: string` 并附加 `enum` 枚举值列表。
5. **完整响应契约**：
   - 每个接口至少包含：`200`（或 `201` 成功）、`400`（参数校验错误）、`401/403`（鉴权错误，若涉及认证）、`500`（系统内部异常）。
   - 必须提供标准统一响应包结构（如包含 `code`、`message`、`data`）。
6. **可读性与示例**：
   - 每个接口必须包含明确的 `summary`（简要操作）和 `description`（详细说明）。
   - 每个 schema 字段必须提供准确的 `description` 与真实的 `example` 示例数据。

# 输入内容
[此处粘贴你的 Controller 代码与关联 DTO/实体类代码]

优化前后生成效果横向对比

很多开发者认为“只要模型够聪明，随便给一句话就能写好”。其实通过对比就能发现，基础提问与结构化提示词产出的文档完全是两个层级的产品：

生产级落地实操 SOP 工作流

为了确保产出的文档可以直接集成到团队的现有工作流中，建议遵循以下三步标准化作业程序：

[步骤一：代码轻量预清洗] -> [步骤二：参数锁定与模型推理] -> [步骤三：静态校验与自动回环修复]

步骤一：代码轻量预清洗与上下文切片

不要把包含复杂 SQL 查询、第三方 SDK 调用的大段业务逻辑代码全量复制给大模型。这会白白浪费上下文配额，还会干扰模型对接口契约的注意力。

•只保留核心部分：保留 Controller 的路由注解（如 `@PostMapping`、`@GetMapping`）、入参注解（`@RequestBody`、`@PathVariable`）、方法签名以及抛出的特定业务异常。

•附带出入参模型：附带相关的 RequestDTO、ResponseVO、Entity 定义，尤其是带有验证注解的声明部分。

步骤二：参数锁定与模型推理执行

•在对应模型 Web 端或 API 调试工具（如 Cherry Studio、NextChat 或官方 Playground）中，将 Temperature 调整为 0.0。

•粘贴上述提示词模板，将清洗后的代码置入 `[输入内容]` 区域。

•观察流式输出过程。如果遇到接口特别多的控制器，在输出接近 4000 Tokens 时，模型如果暂停，直接发送“继续按照上述 OpenAPI 3.0.3 规范输出剩余 paths 与 schemas”，不要让它重新从头开始输出。

步骤三：静态校验与自动回环修复

大模型输出的代码绝不能直接合并上线，必须引入静态校验闭环：

1.本地校验工具验证：

使用官方 Swagger Editor 网页版，或者在本地命令行运行 Node 校验工具：

   npx @stoplight/spectral-cli lint openapi.yaml

2.自动纠错 Prompt：

如果校验器抛出诸如 `schema path is missing property` 或引用悬空（broken reference）等错误，直接将错误日志喂回模型：

“上述生成的 YAML 在经由 Spectral 校验时产生以下错误：`[粘贴错误信息]`。请保持其他结构不变，专门修正这些语法与引用规范问题，重新输出修复后的完整片段。”

一线实操避坑提醒

在实际工程落地中，有几个非常隐蔽的技术陷阱需要特别注意：

1.警惕大模型虚构不存在的全局响应头或安全配置：

大模型在生成认证接口时，喜欢自行脑补 `securitySchemes`。如果项目实际采用自定义 Header（例如 `X-Tenant-Id`、`X-App-Token`），必须在提示词的输入部分明文注明，否则它很可能会默认套用标准的 `bearerAuth (JWT)`，导致联调人员配置错误。

2.日期时间格式的标准化：

大模型经常把时间类型简单定义为 `type: string`。一定要要求其明确使用 `format: date-time`，并符合 ISO 8601（例如 `YYYY-MM-DDTHH:mm:ssZ`），否则基于 OpenAPI 生成前端 TypeScript 接口或后端 SDK 时，无法被转换成对应运行时的 `Date` 实例。

3.循环引用与树形结构：

如果你的 DTO 包含自引用（例如组织架构树 `DepartmentVO` 内部包含 `List children`），大模型容易陷入循环展开。在提示词中应当强调：“遇到树形结构或循环依赖实体时，必须在 schema 中使用指向自身的 `$ref`，严禁无限层级展开嵌套”。