AI的提示词专栏：API 文档 Prompt，从接口描述生成 Swagger
本文围绕从接口描述生成 Swagger 文档的 Prompt 设计展开，先解析 OpenAPI 3.0 规范下 Swagger 文档的八大核心构成，再阐述 Prompt 设计需包含的明确目标、提供上下文、约束格式、补充规则四大要素。通过 RESTful API、带 OAuth2.0 认证的 API、GraphQL API 三个典型场景，给出完整 Prompt 示例与生成的 Swagger 文档节选，并分析设计亮点。还针对文档字段缺失、数据模型未引用、示例不符约束等常见问题，提供 Prompt 优化方案，最后从模型选择、流程标准化、质量管控、工具链集成四方面给出实践建议，助力读者掌握用 Prompt 自动化生成高质量 Swagger 文档的技能，解决手动编写文档的痛点。
人工智能专栏介绍
人工智能学习合集专栏是 AI 学习者的实用工具。它像一个全面的 AI 知识库，把提示词设计、AI 创作、智能绘图等多个细分领域的知识整合起来。无论你是刚接触 AI 的新手，还是有一定基础想提升的人，都能在这里找到合适的内容。从最基础的工具操作方法，到背后深层的技术原理，专栏都有讲解，还搭配了实例教程和实战案例。这些内容能帮助学习者一步步搭建完整的 AI 知识体系，让大家快速从入门进步到精通，更好地应对学习和工作中遇到的 AI 相关问题。
这个系列专栏能教会人们很多实用的 AI 技能。在提示词方面，能让人学会设计精准的提示词，用不同行业的模板高效和 AI 沟通。写作上，掌握从选题到成稿的全流程技巧，用 AI 辅助写出高质量文本。编程时，借助 AI 完成代码编写、调试等工作，提升开发速度。绘图领域，学会用 AI 生成符合需求的设计图和图表。此外，还能了解主流 AI 工具的用法，学会搭建简单智能体，掌握大模型的部署和应用开发等技能，覆盖多个场景，满足不同学习者的需求。
1️⃣ ⚡ 点击进入 AI 的提示词专栏，专栏拆解提示词底层逻辑，从明确指令到场景化描述，教你精准传递需求。还附带包含各行业适配模板：医疗问诊话术、电商文案指令等，附优化技巧，让 AI 输出更贴合预期，提升工作效率。
2️⃣ ⚡ 点击进入 AI 灵感写作专栏，AI 灵感写作专栏，从选题到成稿，全流程解析 AI 写作技巧。涵盖论文框架搭建、小说情节生成等，教你用提示词引导 AI 输出内容，再进行人工润色。附不同文体案例，助你解决写作卡壳，产出高质量文本。
3️⃣ ⚡ 点击进入 AI 辅助编程专栏，AI 辅助编程专栏，通过实例教你用 AI 写代码：从功能描述到调试优化。涵盖前端、后端、数据库等，语言包括HTML5、VUE、Python、Java、C# 等语言，含算法实现、Bug 修复技巧，帮开发者减少重复劳动，专注核心逻辑，提升开发速度。
4️⃣ ⚡ 点击进入 AI 精准绘图专栏，AI 精准绘图，聚焦 AI 绘图在设计场景的落地。详解如何描述风格、元素、用途，生成 logo、商标等。含 Midjourney 等工具参数设置，及修改迭代方法，帮设计新手快速出图，满足商业与个人需求。
5️⃣ ⚡ 点击进入 AI 绘制图表专栏，AI 绘制图表专栏，教你用 AI 工具将数据转化为直观图表。涵盖曲线图数据输入、流程图逻辑梳理等，附 Excel 联动、格式美化技巧，适合学生、职场人快速制作专业图表，提升数据展示效果。
6️⃣ ⚡ 点击进入 AI 的工具集专栏，AI 的工具集专栏，盘点主流 AI 工具：ChatGPT、DeepSeek、 Claude、Gemini、Copilot 等。解析各工具优势，附使用场景与技巧，帮你根据需求选工具，快速上手提升效率，覆盖办公、创作、开发等场景。
7️⃣ ⚡ 点击进入 AI 的智能体专栏，AI 的智能体专栏，解析智能体自主运行原理，包括任务拆解、环境交互等。教你用大模型搭建简单智能体，附多智能体协作案例，适合想探索 AI 自主系统的开发者入门。
8️⃣ ⚡ 点击进入 AI 的大模型专栏，AI 的大模型专栏，详解大模型部署步骤，从本地搭建到云端部署。含 API 调用教程、应用开发案例，教你将大模型集成到项目，掌握企业级 AI 应用开发技能，应对实际业务需求。
一、章节引言
在现代软件开发流程中，API（应用程序编程接口）是连接不同系统、模块的核心桥梁，而API文档则是确保开发团队高效协作、降低沟通成本的关键工具。Swagger（现更名为OpenAPI Specification）作为当前最流行的API文档规范之一，能够通过结构化的JSON或YAML格式，清晰定义API的路径、参数、请求/响应格式、认证方式等核心信息，同时支持自动生成交互式文档页面（如Swagger UI），让开发者无需阅读复杂的文字说明，即可直接在线调试API。
然而，手动编写Swagger文档往往面临诸多痛点：一是效率低下，尤其是当API数量庞大、参数复杂时，开发者需要花费大量时间梳理接口逻辑并按照规范格式编写文档；二是一致性难以保证，不同开发者对Swagger规范的理解存在差异，容易导致文档格式混乱、字段缺失；三是维护成本高，当API接口更新（如参数增减、返回格式调整）时，文档若未能同步更新，会造成"文档与实际接口脱节"，进而引发集成故障。
Prompt工程的出现，为解决API文档编写难题提供了全新思路。通过设计精准的Prompt，我们可以让大语言模型（如ChatGPT、Claude、Gemini）从简单的API接口描述中，自动生成符合Swagger规范的结构化文档，不仅能大幅提升文档编写效率，还能确保格式一致性，降低维护成本。
本章将聚焦"API文档Prompt：从接口描述生成Swagger"这一核心主题，从Swagger文档的核心构成入手，拆解Prompt设计的关键要素，提供不同场景下的Prompt示例（如RESTful API、GraphQL API、带认证的API），并结合实际案例演示如何通过Prompt优化解决文档生成中的常见问题，最终帮助读者掌握"用Prompt自动化生成高质量Swagger文档"的实用技能。
二、Swagger文档核心构成解析
在设计Prompt之前，我们需要先明确Swagger文档的核心构成的要素，这是确保Prompt能精准引导模型生成符合规范文档的基础。根据OpenAPI 3.0（Swagger的最新主流版本）规范，一份完整的Swagger文档主要包含以下8个核心模块，每个模块都有明确的字段要求和作用：
（一）基础信息（Info）
基础信息模块用于描述API的整体概况，帮助开发者快速了解API的用途、版本、维护者等关键信息，是Swagger文档的"封面"。核心字段包括：
title：API的名称（如"用户管理API""订单支付API"），需简洁明了，体现API的核心功能；version：API的版本号（如"1.0.0""2.1.1"），建议遵循语义化版本规范（Major.Minor.Patch）；description：API的详细说明，可包含API的适用场景、功能范围、调用注意事项等；contact：维护者信息，包括姓名、邮箱、网址等，方便开发者在遇到问题时寻求支持；license：API的授权协议（如MIT License、Apache 2.0），明确API的使用权限。
示例（YAML格式）：
yaml
info:
title: 用户管理API
version: 1.0.0
description: 用于实现用户注册、登录、信息查询与修改的RESTful API，支持多终端（Web、App）集成
contact:
name: 张开发
email: dev.zhang@example.com
url: https://dev.example.com
license:
name: MIT License
url: https://opensource.org/licenses/MIT（二）服务器配置（Servers）
服务器配置模块用于定义API的部署地址（如开发环境、测试环境、生产环境），方便开发者根据实际需求选择对应的调用地址。核心字段包括：
url：API服务器的基础地址（如"https://api-dev.example.com/v1""http://test-api.example.com"）；description：对服务器环境的说明（如"开发环境，数据为测试数据，不保证稳定性""生产环境，请勿随意测试"）。
示例（YAML格式）：
yaml
servers:
- url: https://api-dev.example.com/v1
description: 开发环境（仅供内部开发调试使用）
- url: https://api-test.example.com/v1
description: 测试环境（供测试团队验证功能使用）
- url: https://api.example.com/v1
description: 生产环境（正式业务调用地址）（三）路径定义（Paths）
路径定义是Swagger文档的核心模块，用于描述API的具体接口（如"/users""/orders/{orderId}"），以及每个接口支持的HTTP方法（GET、POST、PUT、DELETE等）、参数、请求体、响应等信息。每个路径下的HTTP方法（称为"Operation"）需包含以下核心字段：
summary：接口的简短描述（如"获取用户列表""创建新订单"）；description：接口的详细说明，包括功能逻辑、参数约束、业务规则等；parameters：接口的参数列表，支持路径参数（如{orderId}）、查询参数（如?page=1&size=10）、请求头参数（如Authorization）；requestBody：POST/PUT等方法的请求体格式，需指定媒体类型（如application/json）和数据结构；responses：接口的响应列表，需按HTTP状态码（如200、400、401、500）定义不同响应的格式和说明；tags：接口的标签（如"用户管理""订单操作"），用于对接口进行分类。
示例（YAML格式）：
yaml
paths:
/users/{userId}:
get:
summary: 根据用户ID获取用户详情
description: 通过用户唯一ID（userId）查询用户的基本信息（姓名、手机号、邮箱）和账户状态，仅支持已登录用户调用
tags:
- 用户管理
parameters:
- name: userId
in: path
required: true
description: 用户唯一ID（由系统自动生成，长度为10位数字）
schema:
type: string
pattern: "^[0-9]{10}$"
- name: Authorization
in: header
required: true
description: 登录令牌（格式：Bearer {token}）
schema:
type: string
responses:
'200':
description: 成功获取用户详情
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 200
message:
type: string
example: "success"
data:
type: object
properties:
userId:
type: string
example: "1234567890"
userName:
type: string
example: "张三"
phone:
type: string
example: "13800138000"
email:
type: string
example: "zhangsan@example.com"
status:
type: string
example: "active"
enum: [active, inactive, frozen]
'400':
description: 请求参数错误（如userId格式不正确）
'401':
description: 未登录或令牌过期
'404':
description: 未找到该用户（userId不存在）（四）数据模型（Components -> Schemas）
数据模型模块用于定义API中重复使用的数据结构（如用户信息、订单信息），通过"引用"（$ref）的方式在路径定义中调用，避免重复编写相同的结构，提升文档的可维护性。核心字段包括：
type：数据类型（如object、string、integer、array）；properties：数据对象的字段列表，每个字段需指定类型、示例、说明（可选）、约束（如maxLength、enum）；required：必填字段列表；example：数据模型的示例值，帮助开发者理解数据结构。
示例（YAML格式）：
yaml
components:
schemas:
User:
type: object
description: 用户基本信息模型
required:
- userId
- userName
- phone
properties:
userId:
type: string
description: 用户唯一ID
example: "1234567890"
pattern: "^[0-9]{10}$"
userName:
type: string
description: 用户名（长度1-20位，支持中文、字母、数字）
example: "张三"
maxLength: 20
phone:
type: string
description: 手机号（11位数字）
example: "13800138000"
pattern: "^1[3-9][0-9]{9}$"
email:
type: string
description: 邮箱（可选字段）
example: "zhangsan@example.com"
format: email
status:
type: string
description: 账户状态
example: "active"
enum: [active, inactive, frozen]（五）认证方式（Components -> SecuritySchemes）
认证方式模块用于定义API的安全认证机制（如Bearer令牌、API密钥、Basic认证），通过"security"字段在全局或单个接口中启用认证，确保API的调用安全性。常见的认证类型包括：
type: apiKey：API密钥认证（如通过请求头X-API-Key传递密钥）；type: http：HTTP认证，支持scheme: basic（Basic认证）和scheme: bearer（Bearer令牌，如JWT）；type: oauth2：OAuth2.0认证（适用于第三方授权场景）。
示例（YAML格式）：
yaml
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: 基于JWT的Bearer令牌认证，登录后获取令牌，调用接口时在请求头中携带"Authorization: Bearer {token}"
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: API密钥认证，适用于服务间调用，密钥需向管理员申请（六）标签（Tags）
标签用于对API接口进行分类（如"用户管理""订单操作""商品查询"），方便开发者在Swagger UI中快速筛选和查找接口。每个标签需包含name（标签名称）和description（标签说明）。
示例（YAML格式）：
yaml
tags:
- name: 用户管理
description: 包含用户注册、登录、信息查询、修改、注销等接口
- name: 订单操作
description: 包含订单创建、查询、支付、取消、退款等接口
- name: 商品查询
description: 包含商品列表查询、详情查询、库存查询等接口（七）外部文档（ExternalDocs）
外部文档模块用于链接API的补充文档（如详细的业务逻辑文档、SDK使用指南、常见问题解答），帮助开发者获取更全面的信息。核心字段包括description（文档说明）和url（文档地址）。
示例（YAML格式）：
yaml
externalDocs:
description: 查看完整的API业务逻辑文档和SDK使用指南
url: https://docs.example.com/api/user-management（八）响应示例（Examples）
响应示例模块用于为请求体或响应体提供具体的示例数据，帮助开发者更直观地理解数据格式，减少因格式误解导致的调用错误。示例可以直接定义在requestBody或responses中，也可以通过$ref引用components.examples中的全局示例。
示例（YAML格式）：
yaml
components:
examples:
UserSuccessResponse:
summary: 成功获取用户详情的响应示例
value:
code: 200
message: "success"
data:
userId: "1234567890"
userName: "张三"
phone: "13800138000"
email: "zhangsan@example.com"
status: "active"
UserNotFoundResponse:
summary: 未找到用户的响应示例
value:
code: 404
message: "用户不存在，请检查userId是否正确"
data: null掌握以上8个核心模块的构成，是设计有效Prompt的前提------只有明确告诉模型"需要生成什么内容"，才能确保生成的Swagger文档符合规范、满足实际需求。
三、API文档Prompt设计核心要素
要让大语言模型从接口描述中精准生成Swagger文档，Prompt的设计需要包含"明确目标、提供上下文、约束格式、补充规则"四大核心要素。每个要素都有其特定的作用，共同确保模型生成的文档"准确、完整、规范、可用"。以下将详细拆解每个要素的设计要点，并提供对应的Prompt片段示例。
（一）明确目标：告诉模型"要做什么"
目标明确是Prompt有效的基础。在设计API文档Prompt时，需清晰告知模型两个核心目标：一是"输入内容"（即用户提供的接口描述），二是"输出结果"（即符合OpenAPI 3.0规范的Swagger文档）。若目标模糊，模型可能会生成非结构化的文字说明，而非符合要求的Swagger格式。
设计要点：
- 直接点明输出格式：明确指定"生成OpenAPI 3.0规范的Swagger文档"，并说明使用YAML或JSON格式（推荐YAML，可读性更强）；
- 关联输入与输出：明确告知模型"基于以下接口描述"生成文档，避免模型脱离输入内容自行创作；
- 强调完整性：要求模型覆盖Swagger的核心模块（如Info、Servers、Paths、Components等），避免遗漏关键信息。
Prompt片段示例：
请基于以下API接口描述，生成一份完整的、符合OpenAPI 3.0规范的Swagger文档（使用YAML格式）。文档需包含Info（基础信息）、Servers（服务器配置）、Paths（路径定义）、Components（数据模型与认证方式）、Tags（标签）5个核心模块，确保每个模块的字段完整、符合规范，可直接用于Swagger UI展示和API调试。
【API接口描述】：
接口名称：订单查询接口
功能：通过订单ID查询订单的详细信息（包括订单编号、用户ID、商品列表、金额、支付状态、创建时间）
HTTP方法：GET
接口路径：/orders/{orderId}
参数：
- 路径参数：orderId（订单唯一ID，格式为"ORD+8位数字"，如ORD12345678，必填）
- 请求头参数：Authorization（Bearer令牌，格式为"Bearer {token}"，必填，用于身份认证）
响应：
- 200 OK：成功返回订单详情，响应格式为JSON，包含code（200）、message（"success"）、data（订单信息对象）
- 400 Bad Request：请求参数错误（如orderId格式不正确），响应包含code（400）、message（错误说明）、data（null）
- 401 Unauthorized：未登录或令牌过期，响应包含code（401）、message（"未授权访问，请先登录"）、data（null）
- 404 Not Found：订单不存在，响应包含code（404）、message（"订单不存在，请检查orderId"）、data（null）
服务器环境：
- 开发环境：https://api-dev.example.com/v1
- 生产环境：https://api.example.com/v1
维护者信息：
- 姓名：李开发
- 邮箱：dev.li@example.com（二）提供上下文：告诉模型"相关背景"
上下文信息是模型理解接口逻辑、生成准确文档的关键。若仅提供接口的基础描述（如路径、参数），模型可能无法判断参数约束（如orderId的格式）、业务规则（如"仅已支付订单返回支付时间"）、认证逻辑（如令牌的有效期）等细节，导致生成的文档存在漏洞。
设计要点：
- 补充业务背景：说明API的适用场景（如"供移动端App查询用户订单""供第三方系统同步订单数据"）、业务约束（如"仅管理员可查询所有用户订单，普通用户仅能查询自己的订单"）；
- 明确参数细节：包括参数的格式（如
phone为11位数字）、取值范围（如pageSize最大为100）、默认值（如page默认值为1）、必填性（是否为required: true）； - 说明响应逻辑：包括不同响应状态码的触发条件（如"403 Forbidden"对应"无权限查询该订单"）、响应字段的含义（如
orderStatus的pending表示"待支付"，paid表示"已支付"）； - 提供关联接口：若当前接口与其他接口存在关联（如"创建订单接口（POST /orders）"生成
orderId，供当前查询接口使用），可简要提及，帮助模型理解接口间的逻辑关系。
Prompt片段示例（补充上下文）：
【补充业务上下文】：
1. 适用场景：该订单查询接口仅用于移动端App（iOS/Android）调用，供用户查询自己创建的订单，不支持第三方系统调用；
2. 权限约束：普通用户仅能查询自己的订单（通过Authorization令牌中的用户ID与订单的userID匹配验证），管理员用户（令牌中role为"admin"）可查询所有用户的订单；
3. 参数约束：
- orderId格式严格为"ORD+8位数字"，如"ORD12345678"，不符合格式的请求直接返回400错误；
- 若用户查询非自己的订单且非管理员，返回403 Forbidden，响应message为"无权限查询该订单"；
4. 响应字段说明：
- data中的"productList"为数组，每个元素包含productId（商品ID）、productName（商品名称）、quantity（购买数量）、price（单价，单位：元）；
- data中的"orderStatus"取值范围：pending（待支付）、paid（已支付）、shipped（已发货）、delivered（已送达）、cancelled（已取消）；
- 若orderStatus为"paid"，data中额外返回"payTime"（支付时间，格式：yyyy-MM-dd HH:mm:ss）；若为其他状态，payTime字段不返回；
5. 关联接口：该接口的orderId由"创建订单接口（POST /orders）"生成，创建成功后返回orderId，供用户后续查询使用。（三）约束格式：告诉模型"怎么组织内容"
Swagger文档有严格的格式规范，若模型生成的文档格式混乱（如字段缩进错误、关键字拼写错误、引用路径错误），将无法在Swagger UI中正常展示和使用。因此，在Prompt中需明确约束文档的格式，包括字段命名、缩进规则、引用方式等。
设计要点：
- 规范字段命名：要求模型使用OpenAPI 3.0的标准字段名（如
info、servers、paths、components.schemas），避免自定义非标准字段； - 统一缩进规则：YAML格式依赖缩进表示层级关系，需要求模型使用2个或4个空格缩进（推荐2个，简洁），确保层级清晰；
- 正确使用引用：对于重复的数据结构（如订单模型），要求模型在
components.schemas中定义，并在paths中通过$ref: '#/components/schemas/Order'引用，避免重复编写； - 补充格式检查项：列出常见的格式错误（如
required字段应为数组、schema字段不可遗漏、HTTP状态码需加引号），要求模型规避。
Prompt片段示例（约束格式）：
【Swagger文档格式约束】：
1. 字段命名：严格使用OpenAPI 3.0标准字段名，禁止自定义非标准字段（如"apiInfo"需改为"info"，"apiPaths"需改为"paths"）；
2. 缩进规则：使用2个空格作为一级缩进，确保层级关系清晰（如`paths`下的`/orders/{orderId}`缩进2格，`get`方法再缩进2格）；
3. 引用规范：
- 订单数据结构需在`components.schemas`中定义为"Order"模型，在`paths./orders/{orderId}.get.responses.200.content.application/json.schema.properties.data`中通过`$ref: '#/components/schemas/Order'`引用；
- 认证方式需在`components.securitySchemes`中定义为"BearerAuth"，并在`paths./orders/{orderId}.get`中通过`security: - BearerAuth: []`启用；
4. 格式检查项：
- `required`字段必须为数组类型（如`required: [orderId, Authorization]`），不可为布尔值或字符串；
- 每个`parameter`和`property`必须包含`schema`字段，明确数据类型（如`schema: { type: string, pattern: "^ORD[0-9]{8}$" }`）；
- HTTP状态码（如200、400）需用单引号包裹（如`'200'`），避免YAML将其解析为数字；
- 枚举类型（如`orderStatus`）需通过`enum`字段明确取值范围，不可仅在`description`中说明。（四）补充规则：告诉模型"需要注意什么"
除了基础的格式和内容要求，还需在Prompt中补充"优化规则"，确保生成的Swagger文档不仅"符合规范"，还"易于使用"。这些规则包括示例数据的完整性、文档的可读性、异常场景的覆盖等，直接影响开发者使用文档的体验。
设计要点：
- 示例数据完整：要求模型为每个参数、请求体、响应体提供
example（示例值），且示例需符合参数约束（如orderId示例为"ORD12345678"，而非"123456"）； - 文档可读性强：要求
description字段简洁明了，避免使用技术术语堆砌，同时为复杂字段（如productList）提供详细说明； - 异常场景覆盖：要求模型覆盖常见的异常响应（如400、401、403、404、500），并明确每个异常的触发条件和响应格式；
- 兼容性考虑：若API需支持多终端（如Web、App）或多版本，要求模型在
servers或paths中体现（如通过路径/v1/orders/{orderId}区分版本）； - 可扩展性预留：若API未来可能新增参数或响应字段，要求模型在
description中提示（如"未来可能新增'shippingAddress'字段，用于返回收货地址"）。
Prompt片段示例（补充规则）：
【文档优化规则】：
1. 示例数据要求：
- 每个参数需提供`example`（如`orderId`的`example: "ORD12345678"`，`Authorization`的`example: "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."`）；
- 响应体的`data`字段需提供完整示例（如`productList`示例为`[{"productId": "P001", "productName": "手机", "quantity": 1, "price": 5999.00}]`）；
- 示例值需符合参数约束（如`orderStatus`的示例只能是`pending`、`paid`等枚举值，不可为"未支付"）。
2. 可读性要求：
- `description`字段使用简洁的中文，避免超过200字，关键信息（如参数格式、权限约束）可加粗（使用Markdown加粗语法，如**orderId格式为"ORD+8位数字"**）；
- 复杂字段（如`productList`）需在`description`中说明每个子字段的含义（如"`productList`：订单包含的商品列表，每个元素包含商品ID、名称、购买数量和单价"）。
3. 异常场景覆盖：
- 除已提及的400、401、404响应外，需补充500 Internal Server Error响应（触发条件：服务器内部错误，响应message为"服务器繁忙，请稍后重试"）；
- 每个异常响应需包含`description`（响应说明）和`content`（响应格式示例），不可仅写状态码。
4. 可扩展性预留：
- 在`components.schemas.Order`的`description`中添加："未来可能新增'shippingAddress'（收货地址）和'trackingNumber'（物流单号）字段，具体以API更新通知为准"；
- 在`servers`的`description`中注明："测试环境将在2024年12月31日后停用，届时请切换至开发环境或生产环境"。将以上四大要素整合，即可形成一份完整、有效的API文档Prompt。通过明确目标、提供上下文、约束格式、补充规则，模型能够精准理解用户需求，生成符合规范、易于使用的Swagger文档，大幅降低手动编写的成本。
四、不同场景下的API文档Prompt示例
API的应用场景多样，不同类型的API（如RESTful API、GraphQL API、带认证的API）在Swagger文档生成上有不同的侧重点。本节将针对3个典型场景，提供完整的Prompt示例，并展示模型生成的Swagger文档结果，同时分析每个场景的Prompt设计亮点，帮助读者举一反三。
场景1：RESTful API（基础场景）
RESTful API是最常见的API类型，特点是基于HTTP方法（GET、POST、PUT、DELETE）实现资源的CRUD（创建、查询、更新、删除）操作。该场景的Prompt需重点关注"路径与HTTP方法的对应关系""资源数据模型的定义""参数与响应的完整性"。
1.1 完整Prompt示例
请基于以下RESTful API的接口描述和补充信息，生成一份符合OpenAPI 3.0规范的Swagger文档（YAML格式）。文档需包含Info、Servers、Paths、Components（Schemas+Tags）4个核心模块，严格遵循以下要求：
1. 字段命名：使用OpenAPI 3.0标准字段，缩进为2个空格；
2. 数据模型：在Components.Schemas中定义"Product"模型，包含所有商品字段，通过$ref引用；
3. 示例数据：每个参数、响应体需提供符合约束的example；
4. 异常覆盖：包含200、400、404、500四种响应状态码，明确触发条件。
【接口描述】：
API名称：商品管理API（RESTful）
功能：实现商品的查询（单个/列表）、创建、更新、删除操作
接口列表：
1. GET /products：查询商品列表
- 查询参数：
- page：页码（默认1，正整数）
- size：每页数量（默认10，最大50，正整数）
- category：商品分类（可选，枚举值：electronics、clothing、books）
- 响应（200）：返回分页商品列表，包含total（总数量）、list（商品数组）
2. GET /products/{productId}：查询单个商品详情
- 路径参数：productId（商品唯一ID，格式：P+6位数字，如P123456，必填）
- 响应（200）：返回单个商品完整信息
3. POST /products：创建新商品
- 请求体（application/json）：包含productName（商品名称，必填）、category（分类，必填）、price（单价，必填，正数）、stock（库存，必填，非负整数）、description（描述，可选）
- 响应（201）：返回创建成功的商品信息（含自动生成的productId）
4. PUT /products/{productId}：更新商品信息
- 路径参数：productId（同查询单个商品）
- 请求体（application/json）：字段与创建商品一致，均为可选（仅更新提供的字段）
- 响应（200）：返回更新后的商品信息
5. DELETE /products/{productId}：删除商品
- 路径参数：productId（同查询单个商品）
- 响应（200）：返回删除成功提示
【补充信息】：
- 服务器环境：开发环境（https://api-dev.example.com/v2）、生产环境（https://api.example.com/v2）
- 维护者：王开发（dev.wang@example.com），版本：2.0.0
- 业务约束：创建/更新商品时，price需大于0，stock需大于等于0；删除商品后，查询该productId返回404
- 响应格式：所有响应均为JSON，包含code（状态码）、message（提示信息）、data（数据，可选）1.2 模型生成的Swagger文档（节选）
yaml
openapi: 3.0.0
info:
title: 商品管理API（RESTful）
version: 2.0.0
description: 基于RESTful规范的商品管理API，支持商品的查询（单个/列表）、创建、更新、删除操作
contact:
name: 王开发
email: dev.wang@example.com
servers:
- url: https://api-dev.example.com/v2
description: 开发环境（仅供内部开发调试，数据为测试数据）
- url: https://api.example.com/v2
description: 生产环境（正式业务调用，数据实时更新）
tags:
- name: 商品管理
description: 包含商品的查询、创建、更新、删除等接口，用于管理商品全生命周期
paths:
/products:
get:
summary: 查询商品列表（分页）
description: 按页码、每页数量和分类筛选商品，返回分页列表，**默认每页10条，最大50条**
tags:
- 商品管理
parameters:
- name: page
in: query
required: false
description: 页码（默认1，正整数）
schema:
type: integer
minimum: 1
default: 1
example: 1
- name: size
in: query
required: false
description: 每页数量（默认10，最大50，正整数）
schema:
type: integer
minimum: 1
maximum: 50
default: 10
example: 10
- name: category
in: query
required: false
description: 商品分类（可选，仅支持electronics、clothing、books）
schema:
type: string
enum: [electronics, clothing, books]
example: electronics
responses:
'200':
description: 成功获取商品列表
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 200
message:
type: string
example: "success"
data:
type: object
properties:
total:
type: integer
description: 商品总数量
example: 120
list:
type: array
items:
$ref: '#/components/schemas/Product'
'400':
description: 请求参数错误（如size大于50、category值非法）
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 400
message:
type: string
example: "参数错误：size最大为50，请调整"
data:
type: null
'500':
description: 服务器内部错误
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 500
message:
type: string
example: "服务器繁忙，请稍后重试"
data:
type: null
post:
summary: 创建新商品
description: 新增商品信息，**price需大于0，stock需大于等于0**，productId由系统自动生成
tags:
- 商品管理
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProductCreateUpdate'
examples:
ProductCreateExample:
summary: 创建商品的请求示例
value:
productName: "无线蓝牙耳机"
category: "electronics"
price: 299.00
stock: 100
description: "降噪效果好，续航12小时"
responses:
'201':
description: 商品创建成功
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 201
message:
type: string
example: "商品创建成功"
data:
$ref: '#/components/schemas/Product'
'400':
description: 请求参数错误（如price小于等于0、stock为负数）
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 400
message:
type: string
example: "参数错误：price需大于0，请调整"
data:
type: null
'500':
description: 服务器内部错误
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 500
message:
type: string
example: "服务器繁忙，请稍后重试"
data:
type: null
/products/{productId}:
get:
summary: 查询单个商品详情
description: 通过商品ID（格式：P+6位数字，如P123456）查询商品完整信息
tags:
- 商品管理
parameters:
- name: productId
in: path
required: true
description: 商品唯一ID（格式：P+6位数字，如P123456）
schema:
type: string
pattern: "^P[0-9]{6}$"
example: "P123456"
responses:
'200':
description: 成功获取商品详情
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 200
message:
type: string
example: "success"
data:
$ref: '#/components/schemas/Product'
'400':
description: 请求参数错误（如productId格式不正确）
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 400
message:
type: string
example: "参数错误：productId格式应为P+6位数字（如P123456）"
data:
type: null
'404':
description: 商品不存在（productId未找到或已删除）
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 404
message:
type: string
example: "商品不存在，请检查productId是否正确"
data:
type: null
'500':
description: 服务器内部错误
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 500
message:
type: string
example: "服务器繁忙，请稍后重试"
data:
type: null
put:
summary: 更新商品信息
description: 根据商品ID更新商品信息，**仅更新请求体中提供的字段**，price需大于0，stock需大于等于0
tags:
- 商品管理
parameters:
- name: productId
in: path
required: true
description: 商品唯一ID（格式：P+6位数字，如P123456）
schema:
type: string
pattern: "^P[0-9]{6}$"
example: "P123456"
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProductCreateUpdate'
examples:
ProductUpdateExample:
summary: 更新商品的请求示例（仅更新价格和库存）
value:
price: 279.00
stock: 80
responses:
# 响应内容省略，与POST类似，状态码为200
delete:
summary: 删除商品
description: 根据商品ID删除商品，**删除后查询该productId将返回404**
tags:
- 商品管理
parameters:
- name: productId
in: path
required: true
description: 商品唯一ID（格式：P+6位数字，如P123456）
schema:
type: string
pattern: "^P[0-9]{6}$"
example: "P123456"
responses:
# 响应内容省略，包含200、400、404、500
components:
schemas:
ProductCreateUpdate:
type: object
description: 创建/更新商品时的请求体模型
properties:
productName:
type: string
description: 商品名称（必填，创建时；可选，更新时）
example: "无线蓝牙耳机"
maxLength: 100
category:
type: string
description: 商品分类（必填，创建时；可选，更新时）
example: "electronics"
enum: [electronics, clothing, books]
price:
type: number
format: float
description: 商品单价（必填，创建时；可选，更新时），需大于0
example: 299.00
minimum: 0.01
stock:
type: integer
description: 商品库存（必填，创建时；可选，更新时），需大于等于0
example: 100
minimum: 0
description:
type: string
description: 商品描述（可选）
example: "降噪效果好，续航12小时"
maxLength: 500
Product:
type: object
description: 商品完整信息模型（包含系统生成的productId）
required:
- productId
- productName
- category
- price
- stock
properties:
productId:
type: string
description: 商品唯一ID（系统自动生成，格式：P+6位数字）
example: "P123456"
pattern: "^P[0-9]{6}$"
productName:
type: string
description: 商品名称
example: "无线蓝牙耳机"
maxLength: 100
category:
type: string
description: 商品分类
example: "electronics"
enum: [electronics, clothing, books]
price:
type: number
format: float
description: 商品单价（大于0）
example: 299.00
minimum: 0.01
stock:
type: integer
description: 商品库存（大于等于0）
example: 100
minimum: 0
description:
type: string
description: 商品描述（可选）
example: "降噪效果好，续航12小时"
maxLength: 500
createTime:
type: string
format: date-time
description: 商品创建时间（系统自动生成）
example: "2024-05-20T14:30:00"
updateTime:
type: string
format: date-time
description: 商品最后更新时间（系统自动生成）
example: "2024-05-20T15:45:00"1.3 Prompt设计亮点分析
- 接口列表结构化：将5个接口按"HTTP方法+路径"分类列出，清晰告知模型接口间的逻辑关系；
- 业务约束明确：强调"price大于0、stock非负""删除后返回404"等规则，避免模型生成不符合业务逻辑的文档；
- 数据模型拆分：将"创建/更新请求体"和"商品完整信息"拆分为两个模型（
ProductCreateUpdate和Product），符合RESTful API的参数设计习惯，避免冗余。
场景2：带OAuth2.0认证的API（安全场景）
部分API需要通过OAuth2.0认证（如第三方登录、开放平台API），这类API的Swagger文档需重点体现"认证流程""令牌传递方式""权限范围"。Prompt需明确OAuth2.0的授权类型（如Authorization Code、Client Credentials）、令牌端点、权限范围等信息。
2.1 完整Prompt示例
请基于以下带OAuth2.0认证的API描述，生成符合OpenAPI 3.0规范的Swagger文档（YAML格式）。文档需重点突出OAuth2.0认证配置，包含Info、Servers、Paths、Components（SecuritySchemes+Schemas+Tags）5个模块，要求如下：
1. 认证配置：在Components.SecuritySchemes中定义OAuth2.0认证，明确授权类型、令牌端点、权限范围；
2. 权限关联：每个接口需通过security字段关联对应的权限范围（如read:user需user:read范围）；
3. 流程说明：在Info.Description中简要说明OAuth2.0认证流程，帮助开发者理解如何获取令牌；
4. 格式规范：缩进2个空格，示例数据符合实际场景，异常响应覆盖401（未授权）、403（无权限）。
【API描述】：
API名称：用户开放API（OAuth2.0认证）
功能：为第三方应用提供用户信息查询接口，需通过OAuth2.0认证
接口列表：
1. GET /users/me：查询当前授权用户的基本信息（姓名、手机号、邮箱）
- 权限范围：user:read（读取用户信息权限）
- 响应（200）：返回当前用户信息
2. GET /users/me/orders：查询当前授权用户的订单列表（分页）
- 权限范围：user:read + order:read（需同时拥有用户和订单读取权限）
- 查询参数：page（默认1）、size（默认10，最大20）
- 响应（200）：返回分页订单列表
【OAuth2.0认证信息】：
- 授权类型：Authorization Code（授权码模式）
- 授权端点：https://auth.example.com/oauth/authorize
- 令牌端点：https://auth.example.com/oauth/token
- 刷新令牌端点：https://auth.example.com/oauth/refresh-token
- 权限范围：
- user:read：读取用户基本信息
- order:read：读取用户订单信息
- 令牌传递方式：请求头Authorization，格式：Bearer {access_token}
- 令牌有效期：access_token有效期2小时，refresh_token有效期30天
【补充信息】：
- 服务器环境：测试环境（https://api-test.example.com/open/v1）、生产环境（https://api.example.com/open/v1）
- 维护者：赵开发（dev.zhao@example.com），版本：1.0.0
- 异常说明：
- 401：未携带令牌、令牌过期或无效
- 403：令牌无对应接口的权限范围（如无order:read范围调用订单接口）
- 400：查询参数错误（如size大于20）2.2 模型生成的Swagger文档（节选）
yaml
openapi: 3.0.0
info:
title: 用户开放API（OAuth2.0认证）
version: 1.0.0
description: 为第三方应用提供的用户信息查询API，**需通过OAuth2.0认证（Authorization Code模式）** 才能调用。认证流程：1. 第三方应用引导用户到授权端点获取授权码；2. 使用授权码到令牌端点获取access_token和refresh_token；3. 调用接口时在请求头携带"Authorization: Bearer {access_token}"。access_token有效期2小时，过期后可使用refresh_token刷新。
contact:
name: 赵开发
email: dev.zhao@example.com
servers:
- url: https://api-test.example.com/open/v1
description: 测试环境（第三方应用测试使用，数据为模拟数据）
- url: https://api.example.com/open/v1
description: 生产环境（正式第三方应用调用，数据为真实用户数据）
tags:
- name: 用户开放接口
description: 为第三方应用提供的用户信息查询接口，需OAuth2.0认证并拥有对应权限范围
paths:
/users/me:
get:
summary: 查询当前授权用户的基本信息
description: 获取当前access_token对应的用户基本信息（姓名、手机号、邮箱），**需拥有user:read权限范围**
tags:
- 用户开放接口
security:
- OAuth2Auth:
- user:read
responses:
'200':
description: 成功获取当前用户信息
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 200
message:
type: string
example: "success"
data:
type: object
properties:
userName:
type: string
example: "李四"
phone:
type: string
example: "13900139000"
email:
type: string
example: "lisi@example.com"
'401':
description: 未授权（未携带令牌、令牌过期或无效）
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 401
message:
type: string
example: "未授权访问，请检查令牌是否有效或已过期"
data:
type: null
'403':
description: 无权限（令牌缺少user:read权限范围）
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 403
message:
type: string
example: "无权限访问，令牌需包含user:read权限范围"
data:
type: null
'500':
description: 服务器内部错误
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 500
message:
type: string
example: "服务器繁忙，请稍后重试"
data:
type: null
/users/me/orders:
get:
summary: 查询当前授权用户的订单列表（分页）
description: 获取当前用户的订单分页列表，**需同时拥有user:read和order:read权限范围**，默认每页10条，最大20条
tags:
- 用户开放接口
security:
- OAuth2Auth:
- user:read
- order:read
parameters:
- name: page
in: query
required: false
description: 页码（默认1，正整数）
schema:
type: integer
minimum: 1
default: 1
example: 1
- name: size
in: query
required: false
description: 每页数量（默认10，最大20，正整数）
schema:
type: integer
minimum: 1
maximum: 20
default: 10
example: 10
responses:
# 响应内容省略，包含200、400、401、403、500
components:
securitySchemes:
OAuth2Auth:
type: oauth2
description: 基于OAuth2.0的Authorization Code模式认证，需获取access_token并在请求头携带
flows:
authorizationCode:
authorizationUrl: https://auth.example.com/oauth/authorize
tokenUrl: https://auth.example.com/oauth/token
refreshUrl: https://auth.example.com/oauth/refresh-token
scopes:
user:read: 读取用户基本信息的权限
order:read: 读取用户订单信息的权限
schemas:
# 数据模型省略，与场景1类似2.3 Prompt设计亮点分析
- 认证信息完整：明确OAuth2.0的授权类型、端点、权限范围，确保模型生成的
securitySchemes符合规范； - 权限关联清晰：为每个接口指定所需的权限范围，模型通过
security字段准确关联，避免权限遗漏； - 流程说明直观：在
info.description中补充认证流程，帮助非专业开发者理解如何使用API，提升文档实用性。
场景3：GraphQL API（非REST场景）
GraphQL API与RESTful API不同，它通过单个端点接收查询请求，允许客户端自定义返回字段。这类API的Swagger文档需重点体现"GraphQL查询类型（Query/Mutation）""查询结构""参数类型""返回字段定义"。Prompt需明确GraphQL的schema定义、查询示例等信息。
3.1 完整Prompt示例
请基于以下GraphQL API的描述，生成符合OpenAPI 3.0规范的Swagger文档（YAML格式）。GraphQL API通过单个POST端点（/graphql）接收请求，文档需重点包含GraphQL查询的schema定义、请求体示例、响应示例，要求如下：
1. 路径定义：仅定义POST /graphql一个路径，描述支持的Query和Mutation类型；
2. 请求体：使用application/json格式，包含query（查询语句）和variables（变量，可选）字段，提供多个查询示例；
3. 数据模型：在Components.Schemas中定义GraphQL的核心类型（如User、Order）和查询结果类型；
4. 说明清晰：在description中解释GraphQL与REST的区别，帮助开发者快速上手。
【API描述】：
API名称：用户订单GraphQL API
功能：通过GraphQL查询语言，让客户端自定义获取用户信息和订单信息，支持查询单个用户、用户订单列表
端点：POST /graphql（唯一端点）
GraphQL Schema定义：
- 类型定义：
1. User类型：包含id（String，必填）、name（String，必填）、phone（String，必填）、email（String，可选）
2. Order类型：包含id（String，必填）、userId（String，必填）、productName（String，必填）、price（Float，必填）、status（String，枚举：pending/paid/shipped）
3. Query类型：
- getUser(id: String!): User（通过用户ID查询单个用户，id为必填参数）
- getUserOrders(userId: String!, page: Int = 1, size: Int = 10): [Order]（通过用户ID查询订单列表，支持分页）
- 无Mutation类型（仅查询功能）
【补充信息】：
- 服务器环境：开发环境（https://graphql-dev.example.com/api）、生产环境（https://graphql.example.com/api）
- 维护者：孙开发（dev.sun@example.com），版本：1.0.0
- 请求示例1：查询用户ID为"U123"的用户信息（仅返回id、name、phone）
query {
getUser(id: "U123") {
id
name
phone
}
}
- 请求示例2：查询用户ID为"U123"的订单列表（第1页，10条/页，返回id、productName、status）
query GetUserOrders($userId: String!, $page: Int, $size: Int) {
getUserOrders(userId: $userId, page: $page, size: $size) {
id
productName
status
}
}
variables: { "userId": "U123", "page": 1, "size": 10 }
- 异常说明：400（查询语句语法错误）、404（用户/订单不存在）、500（服务器错误）3.2 模型生成的Swagger文档（节选）
yaml
openapi: 3.0.0
info:
title: 用户订单GraphQL API
version: 1.0.0
description: 基于GraphQL的用户订单查询API，**与REST不同，仅通过POST /graphql一个端点接收请求**，客户端可自定义查询返回的字段（无需获取冗余数据）。支持查询单个用户信息和用户订单列表，查询语句需符合GraphQL语法规范。
contact:
name: 孙开发
email: dev.sun@example.com
servers:
- url: https://graphql-dev.example.com/api
description: 开发环境（GraphQL调试可用，数据为模拟数据）
- url: https://graphql.example.com/api
description: 生产环境（正式业务调用，数据实时更新）
tags:
- name: GraphQL查询接口
description: 通过单个GraphQL端点，支持用户和订单信息的自定义查询
paths:
/graphql:
post:
summary: GraphQL查询端点（唯一）
description: 接收GraphQL查询请求，支持Query类型（getUser、getUserOrders），客户端可自定义返回字段。请求体需包含query（查询语句），variables（变量，可选），格式为application/json。
tags:
- GraphQL查询接口
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- query
properties:
query:
type: string
description: GraphQL查询语句（需符合Schema定义）
example: "query { getUser(id: \"U123\") { id name phone } }"
variables:
type: object
description: 查询变量（可选，用于动态传递参数）
example: { "userId": "U123", "page": 1, "size": 10 }
examples:
GetUserExample:
summary: 查询单个用户信息（仅返回id、name、phone）
value:
query: "query GetUser($id: String!) { getUser(id: $id) { id name phone } }"
variables: { "id": "U123" }
GetUserOrdersExample:
summary: 查询用户订单列表（分页，返回id、productName、status）
value:
query: "query GetUserOrders($userId: String!, $page: Int, $size: Int) { getUserOrders(userId: $userId, page: $page, size: $size) { id productName status } }"
variables: { "userId": "U123", "page": 1, "size": 10 }
responses:
'200':
description: 查询成功（即使未找到数据，状态码仍为200，错误信息在errors字段中）
content:
application/json:
schema:
type: object
properties:
data:
type: object
description: 查询结果数据（查询成功且有数据时返回）
example:
getUser:
id: "U123"
name: "王五"
phone: "13700137000"
errors:
type: array
description: 查询错误信息（语法错误、参数错误、数据未找到等，无错误时不返回）
items:
type: object
properties:
message:
type: string
example: "用户不存在（id: U1234）"
locations:
type: array
items:
type: object
properties:
line:
type: integer
example: 2
column:
type: integer
example: 5
'400':
description: 请求错误（如GraphQL查询语句语法错误、请求体格式不正确）
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
message:
type: string
example: "GraphQL语法错误：字段'userName'在User类型中不存在（正确字段为'name'）"
locations:
type: array
items:
type: object
properties:
line:
type: integer
example: 3
column:
type: integer
example: 6
'500':
description: 服务器内部错误（如GraphQL服务异常）
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
message:
type: string
example: "服务器内部错误，请稍后重试"
components:
schemas:
User:
type: object
description: GraphQL中的User类型定义
required:
- id
- name
- phone
properties:
id:
type: string
description: 用户唯一ID
example: "U123"
name:
type: string
description: 用户名
example: "王五"
phone:
type: string
description: 手机号
example: "13700137000"
email:
type: string
description: 邮箱（可选字段）
example: "wangwu@example.com"
Order:
type: object
description: GraphQL中的Order类型定义
required:
- id
- userId
- productName
- price
- status
properties:
id:
type: string
description: 订单唯一ID
example: "ORD456"
userId:
type: string
description: 所属用户ID（与User.id关联）
example: "U123"
productName:
type: string
description: 商品名称
example: "笔记本电脑"
price:
type: number
format: float
description: 订单金额
example: 6999.00
status:
type: string
description: 订单状态
example: "paid"
enum: [pending, paid, shipped]
Query:
type: object
description: GraphQL中的Query类型定义（支持的查询操作）
properties:
getUser:
type: object
description: 通过用户ID查询单个用户
properties:
parameters:
type: object
properties:
id:
type: string
description: 用户ID（必填）
example: "U123"
returnType:
$ref: '#/components/schemas/User'
getUserOrders:
type: object
description: 通过用户ID查询订单列表（分页）
properties:
parameters:
type: object
properties:
userId:
type: string
description: 用户ID（必填）
example: "U123"
page:
type: integer
description: 页码（默认1）
example: 1
size:
type: integer
description: 每页数量（默认10）
example: 10
returnType:
type: array
items:
$ref: '#/components/schemas/Order'3.3 Prompt设计亮点分析
- 端点单一化：明确GraphQL仅需定义
/graphql一个POST端点，避免模型生成多个路径； - 查询示例丰富：提供2个完整的请求示例（含query和variables），帮助模型理解GraphQL的请求格式；
- 响应特殊说明：强调GraphQL的"200状态码+errors字段"特性，避免模型按REST习惯返回404状态码，符合GraphQL的实际使用场景。
五、Prompt优化与常见问题解决
在使用Prompt生成Swagger文档时，可能会遇到"模型生成的文档格式错误""字段遗漏""示例不符合约束"等问题。本节将总结5个常见问题，并提供对应的Prompt优化方案，帮助读者提升文档生成质量。
问题1：模型生成的Swagger文档字段缺失（如遗漏Servers或Components）
问题表现：
模型生成的文档仅包含paths和info模块，缺失servers（服务器配置）或components.schemas（数据模型），导致文档无法完整描述API的部署地址和数据结构。
原因分析：
Prompt中未明确要求模型覆盖所有核心模块，或对模块的提及过于模糊（如仅说"生成Swagger文档"，未列举需包含的模块）。
Prompt优化方案：
在Prompt中"明确列出需包含的模块"，并使用"必须/需"等强约束词汇，确保模型不遗漏。
优化前Prompt片段：
请基于以下接口描述，生成符合OpenAPI 3.0规范的Swagger文档（YAML格式）。优化后Prompt片段：
请基于以下接口描述，生成符合OpenAPI 3.0规范的Swagger文档（YAML格式）。文档**必须包含且不可遗漏**以下5个核心模块：
1. Info：包含title、version、description、contact；
2. Servers：包含开发环境和生产环境的url与description；
3. Paths：包含所有接口的HTTP方法、参数、请求体、响应；
4. Components：包含Schemas（数据模型）和SecuritySchemes（若有认证）；
5. Tags：对接口进行分类，每个接口需关联对应的tag。问题2：数据模型未通过$ref引用，导致文档冗余
问题表现：
模型在paths的响应中重复编写相同的数据结构（如订单信息），未在components.schemas中定义统一模型并通过$ref引用，导致文档冗长、维护困难。
原因分析：
Prompt中未明确要求"使用$ref引用重复数据结构"，模型默认按"简单直接"的方式生成，未考虑文档的可维护性。
Prompt优化方案：
在Prompt中"明确要求重复数据结构需定义在Components.Schemas中，并通过$ref引用"，同时举例说明引用格式。
优化前Prompt片段：
请为订单查询接口生成Swagger文档，响应中需包含订单的id、userId、productName、price、status字段。优化后Prompt片段：
请为订单查询接口生成Swagger文档，需满足以下要求：
1. 订单数据结构（包含id、userId、productName、price、status字段）需在`components.schemas`中定义为"Order"模型；
2. 在`paths`的响应（如200 OK的data字段）中，通过`$ref: '#/components/schemas/Order'`引用该模型，**禁止重复编写订单字段**；
3. Order模型需包含每个字段的type、description、example和约束（如status的enum）。问题3：示例数据不符合参数约束（如格式错误、取值非法）
问题表现：
模型生成的示例数据不符合Prompt中定义的约束，如orderId的约束为"ORD+8位数字"，但示例为"12345678"；price的约束为"大于0"，但示例为"-100"。
原因分析：
Prompt中虽提及参数约束，但未明确"示例数据需符合约束"，模型可能忽略约束仅生成"格式正确但取值非法"的示例。
Prompt优化方案：
在Prompt中"明确要求示例数据需符合参数约束"，并对关键参数的示例格式进行单独说明。
优化前Prompt片段：
orderId的格式为"ORD+8位数字"，请生成示例。优化后Prompt片段：
参数约束与示例要求：
1. orderId：格式为"ORD+8位数字"（如ORD12345678），示例**必须严格符合该格式**，禁止使用"12345678""ORD123"等错误格式；
2. price：取值需大于0（最小0.01），示例**必须为正数**（如299.00、10.50），禁止使用0、-50等非法值；
3. status：枚举值为pending/paid/shipped，示例**只能从这三个值中选择**，禁止使用"未支付""已发货"等中文描述。问题4：认证方式未与接口关联（如定义了BearerAuth但未启用）
问题表现：
模型在components.securitySchemes中定义了BearerAuth认证方式，但在paths的接口中未通过security字段关联，导致接口实际不要求认证，与业务需求不符。
原因分析：
Prompt中未明确"每个接口需关联对应的认证方式"，模型仅完成了认证方式的定义，未进行接口关联。
Prompt优化方案：
在Prompt中"明确要求每个接口需通过security字段关联认证方式"，并指定关联的认证名称（如BearerAuth）。
优化前Prompt片段：
请定义BearerAuth认证方式（HTTP Bearer令牌）。优化后Prompt片段：
认证配置要求：
1. 在`components.securitySchemes`中定义"BearerAuth"认证方式（type: http，scheme: bearer，bearerFormat: JWT）；
2. **所有接口（GET /users、POST /orders等）必须通过security字段关联BearerAuth**，关联格式为：
security:
- BearerAuth: []
3. 在接口的description中说明"需携带Authorization请求头（格式：Bearer {token}）"。问题5：GraphQL API的响应未包含errors字段
问题表现：
模型生成的GraphQL API响应仅包含data字段，未包含errors字段，无法体现GraphQL"查询错误通过errors返回，状态码仍为200"的特性，导致开发者误解错误处理逻辑。
原因分析：
Prompt中未明确GraphQL响应的特殊格式，模型按REST API的习惯生成响应（错误返回404/500状态码，无errors字段）。
Prompt优化方案：
在Prompt中"专门说明GraphQL响应的格式要求"，强调errors字段的作用和包含场景。
优化前Prompt片段：
GraphQL API的响应需包含查询结果。优化后Prompt片段：
GraphQL API响应格式要求（与REST不同）：
1. 状态码：无论查询成功/失败（如数据未找到、语法错误），HTTP状态码均为200；
2. data字段：查询成功且有数据时返回，包含查询结果；
3. errors字段：查询失败时返回（如语法错误、参数错误、数据未找到），需包含message（错误信息）和locations（错误位置，如行号、列号）；
4. 示例：未找到用户时，响应应为：
{
"errors": [
{
"message": "用户不存在（id: U1234）",
"locations": [{"line": 2, "column": 5}]
}
]
}
禁止返回404状态码。六、章节总结与实践建议
本章围绕"API文档Prompt：从接口描述生成Swagger"展开，从Swagger文档的核心构成入手，拆解了Prompt设计的四大核心要素，并通过RESTful API、带OAuth2.0认证的API、GraphQL API三个典型场景提供了可落地的Prompt示例与优化方案，最终形成了"理解规范→设计Prompt→生成文档→解决问题"的完整方法论。通过本章内容的学习，读者应能掌握"用Prompt自动化生成高质量Swagger文档"的核心能力，有效解决手动编写文档效率低、一致性差、维护成本高的痛点。
为帮助读者将理论转化为实践，结合实际开发中的常见需求，此处提供4条针对性的实践建议，覆盖工具选择、流程落地、质量管控等关键环节：
（一）选择适配的大语言模型，平衡效率与精度
不同大语言模型对Swagger文档生成的支持能力存在差异，需根据需求选择适配的模型：
- 追求高精度与规范度：优先选择GPT-4、Claude 3等能力较强的闭源模型。这类模型对OpenAPI 3.0规范的理解更深入，能精准识别参数约束、认证逻辑等细节，生成的文档格式错误率低（如$ref引用正确、枚举字段完整），尤其适合带复杂认证（如OAuth2.0）或特殊格式（如GraphQL）的API场景；
- 追求低成本与批量生成：可选择Gemini Pro、Qwen-72B等开源或低成本模型。若需批量生成大量简单RESTful API的文档（如内部系统的基础接口），可基于本章提供的Prompt模板，结合模型的批量调用能力（如通过API批量传入接口描述），实现"一次Prompt，多文档输出"，大幅提升效率；
- 本地部署需求：若API涉及敏感信息（如医疗、金融领域的接口参数），可选择Llama 3、Mistral等支持本地部署的开源模型，在私有环境中使用Prompt生成文档，避免敏感数据泄露。
（二）构建"接口描述模板+Prompt模板"的标准化流程
为确保团队内文档生成的一致性，建议构建标准化的输入输出流程：
-
统一接口描述模板 ：设计结构化的接口描述模板，要求开发人员在提交接口需求时，按模板填写关键信息（如接口名称、HTTP方法、参数约束、响应格式、业务规则）。例如：
【接口基本信息】 名称：用户注册接口 功能：用户通过手机号+验证码完成注册，系统自动生成userId HTTP方法：POST 路径：/users/register 【请求参数】 - 表单参数： 1. phone：手机号（11位数字，必填，需校验格式） 2. verifyCode：验证码（6位数字，必填，有效期5分钟） 3. password：密码（8-20位，含字母+数字，必填） 【响应格式】 - 200 OK：{code:200, message:"注册成功", data:{userId:"U123456"}} - 400 Bad Request：{code:400, message:"参数错误（如手机号格式不正确）", data:null} 【业务约束】 - 同一手机号1小时内最多注册3次 - 密码需加密传输（MD5加密） -
固化Prompt模板 ：基于本章的四大核心要素，构建通用的Swagger文档Prompt模板，将"接口描述模板"的内容作为变量嵌入Prompt中。例如：
请基于以下接口描述，生成符合OpenAPI 3.0规范的Swagger文档（YAML格式），需包含Info、Servers、Paths、Components、Tags模块，要求如下： 1. 数据模型：重复使用的结构（如用户信息）需在Components.Schemas中定义，通过$ref引用； 2. 示例数据：所有参数、响应需提供符合约束的example； 3. 异常覆盖：包含200、400、401（若有认证）、404、500响应； 4. 业务说明：将接口描述中的"业务约束"补充到对应接口的description中。 【接口描述】 {此处嵌入开发人员填写的结构化接口描述}
通过标准化的输入（接口描述模板）和固定的Prompt模板，可减少团队内沟通成本，确保生成的Swagger文档格式统一、信息完整。
（三）建立"自动生成+人工校验"的质量管控机制
Prompt生成的Swagger文档虽能满足基础规范，但仍需结合人工校验确保可用性，建议建立以下管控机制：
- 自动校验工具前置 ：使用Swagger官方提供的Swagger Editor或开源工具（如openapi-validator），对模型生成的文档进行自动校验，检查是否存在格式错误（如字段缩进错误、关键字拼写错误）、规范冲突（如参数类型不匹配）等问题，快速定位并修正基础错误；
- 人工校验重点环节 ：自动校验通过后，人工重点检查3个核心环节：
- 业务逻辑一致性：确认文档中的参数约束、响应规则与实际接口逻辑一致（如"同一手机号1小时内最多注册3次"是否在description中说明）；
- 认证与权限准确性：若接口需认证，检查security字段是否正确关联认证方式（如BearerAuth），权限范围是否匹配（如订单接口是否关联order:read权限）；
- 示例数据实用性：确认示例数据是否符合实际使用场景（如userId示例是否为系统真实格式、token示例是否包含正确前缀），避免因示例无效导致开发者误解；
- 版本同步机制：当API接口更新（如新增参数、修改响应格式）时，需同步更新Swagger文档。可在接口迭代流程中增加"文档更新"环节，要求开发人员基于更新后的接口描述，重新使用Prompt生成文档，并通过校验后同步至Swagger UI，确保"文档与接口同步"。
（四）结合工具链集成，实现文档全生命周期管理
将Prompt生成的Swagger文档与开发工具链集成，可进一步提升文档的实用性和维护效率：
- 与API开发工具集成：将生成的Swagger文档导入Postman、Apifox等API调试工具，自动生成接口测试用例，开发者可直接基于文档进行接口调试，无需手动输入参数；
- 与CI/CD流程集成：在CI/CD pipeline中增加"Swagger文档生成"步骤，当代码提交或接口定义更新时，自动调用大语言模型API（如OpenAI API），基于最新的接口描述生成文档，并同步至企业内部的文档平台（如Confluence），实现文档的自动更新；
- 与文档展示平台集成：将通过校验的Swagger文档部署到Swagger UI或企业级API网关（如Kong、APISIX），提供交互式的文档展示页面，开发者可在线查看接口详情、调试接口，甚至自动生成SDK（如通过Swagger Codegen生成Java、Python SDK），降低API的使用门槛。
通过工具链集成，可实现Swagger文档从"生成→校验→部署→使用"的全生命周期管理，让文档真正服务于开发、测试、集成等各个环节，最大化其价值。
综上，"API文档Prompt：从接口描述生成Swagger"的核心价值在于"以Prompt为桥梁，连接自然语言描述与标准化文档"，帮助团队摆脱繁琐的手动编写工作。但需注意，Prompt是提升效率的工具，而非替代人工的"万能方案"，只有结合对Swagger规范的理解、标准化的流程、严格的质量管控，才能真正生成"规范、准确、可用"的Swagger文档，为API的高效协作提供支撑。
联系博主
xcLeigh 博主，全栈领域优质创作者，博客专家，目前，活跃在CSDN、微信公众号、小红书、知乎、掘金、快手、思否、微博、51CTO、B站、腾讯云开发者社区、阿里云开发者社区等平台，全网拥有几十万的粉丝，全网统一IP为 xcLeigh。希望通过我的分享，让大家能在喜悦的情况下收获到有用的知识。主要分享编程、开发工具、算法、技术学习心得等内容。很多读者评价他的文章简洁易懂，尤其对于一些复杂的技术话题，他能通过通俗的语言来解释，帮助初学者更好地理解。博客通常也会涉及一些实践经验，项目分享以及解决实际开发中遇到的问题。如果你是开发领域的初学者，或者在学习一些新的编程语言或框架，关注他的文章对你有很大帮助。
亲爱的朋友，无论前路如何漫长与崎岖，都请怀揣梦想的火种，因为在生活的广袤星空中，总有一颗属于你的璀璨星辰在熠熠生辉，静候你抵达。
愿你在这纷繁世间，能时常收获微小而确定的幸福，如春日微风轻拂面庞，所有的疲惫与烦恼都能被温柔以待，内心永远充盈着安宁与慰藉。
至此，文章已至尾声，而您的故事仍在续写，不知您对文中所叙有何独特见解？期待您在心中与我对话，开启思想的新交流。
💞 关注博主 🌀 带你实现畅游前后端！
🏰 大屏可视化 🌀 带你体验酷炫大屏！
💯 神秘个人简介 🌀 带你体验不一样得介绍！
🥇 从零到一学习Python 🌀 带你玩转Python技术流！
🏆 前沿应用深度测评 🌀 前沿AI产品热门应用在线等你来发掘！
💦 注 ：本文撰写于CSDN平台 ,作者：xcLeigh （所有权归作者所有） ，https://xcleigh.blog.csdn.net/，如果相关下载没有跳转，请查看这个地址，相关链接没有跳转，皆是抄袭本文，转载请备注本文原地址。
📣 亲，码字不易，动动小手，欢迎 点赞 ➕ 收藏，如 🈶 问题请留言（或者关注下方公众号，看见后第一时间回复，还有海量编程资料等你来领！），博主看见后一定及时给您答复 💌💌💌