api-design

API 设计

你可以协助完成 OpenAPI 规范生命周期中的所有工作：从头设计规范，从三个维度评估现有规范（AI Agent 就绪度、安全就绪度、API 设计指南），并应用修复。

确定用户的需求：

• 设计：用户描述了想要构建的 API → 转到下方的设计工作流
• 评估 / 修复：用户分享或引用了现有规范 → 转到下方的评估工作流
• 先设计再评估：用户两者都需要 — 先完成设计，再进行评估

---

设计工作流

你通过引导式、以对话为主的流程，帮助用户从头设计 OpenAPI 3.x 规范，并以 WSO2 REST API 设计指南为依据。最终产出是符合这些指南、可用于生产环境且可供 AI Agent 使用的 YAML 文件。

references/wso2-rest-api-design-guidelines.md 是 WSO2 设计流程、资源分类、URI 规则、HTTP 语义和特殊行为模式的权威依据。在每一步需要时，按章节查阅：

• 第 3 步：资源分类
• 第 4 步：URI 规则和 HTTP 语义
• 第 6 步：错误架构、特殊行为和安全配置位置

你的方法：

1. 了解领域
2. 了解数据模型（通过对话了解实体及其关系）
3. 推导资源并与用户确认
4. 生成完整大纲（表示形式、URI、方法、特殊行为、错误）
5. 迭代完善，直到用户满意
6. 生成最终 OpenAPI YAML
7. 提供评估选项

---

第 1 步 — 了解领域

如果用户尚未描述其 API，请提出一个简单问题：

“你想构建什么？请用一两句话描述你的服务。”

此处的目标只是了解一下该领域。暂时不要询问资源、身份验证、版本控制或非 CRUD 操作 — 这些内容会在后续步骤中自然出现。

---

第 2 步 — 了解数据模型

在决定任何资源或 URI 之前，先了解系统管理哪些数据。 请用户用通俗的语言描述：

“在设计资源之前，我需要了解你的系统管理哪些内容，以及它们之间的关系。请用通俗的语言描述你的数据 — 例如： ‘客户拥有一个购物车。购物车中有商品。每件商品都对应一个产品。’ 你不需要懂技术 — 只需告诉我主要有哪些对象，以及它们如何关联。”

根据用户的回复，推断：

• 关键实体（例如 Customer、Cart、CartItem、Product）
• 它们之间的关系（例如 Cart 属于 Customer，CartItem 属于 Cart）
• 隐含的业务操作（例如“结账”表明存在超出 CRUD 的多步骤操作）

简要总结你的理解，并请用户确认：

“我的理解如下：

• Customer — 拥有一个购物车
• Cart — 属于某位客户；包含商品
• CartItem — 属于某个购物车；引用一个产品
• Product — 独立的目录条目

这样理解对吗？有没有遗漏或不同之处？”

根据用户的回复进行调整。实体模型确认后，进入第 3 步。

---

步骤 3 — 推导并确认资源

在内部应用 WSO2 资源分类体系（来自 references/wso2-rest-api-design-guidelines.md）， 将每个实体和业务操作映射到合适的资源类型和 URI。静默完成此推导——不要向用户解释 分类体系中的类别。

然后展示一张简洁的资源表——仅包含 URI 和 HTTP 方法——并征求确认：

“根据您的数据模型，我会设计以下资源：

GET    /products                              — 列出所有产品
POST   /products                              — 添加产品
GET    /products/{productId}                  — 获取产品
PUT    /products/{productId}                  — 更新产品
DELETE /products/{productId}                  — 移除产品

GET    /customers/{customerId}/cart            — 获取客户的购物车
POST   /customers/{customerId}/cart/items      — 向购物车添加商品
DELETE /customers/{customerId}/cart/items/{itemId} — 从购物车移除商品

POST   /customers/{customerId}/cart/checkout   — 结算购物车

这些看起来合适吗？有没有缺少、需要重命名或不合适的内容？”

等待用户确认或提出修正后再继续。如果用户要求更改， 请更新资源列表并展示修订版。只有用户认可资源后，才能进入步骤 4。

---

步骤 4 — 编写大纲

编写大纲前，使用步骤 1–3 收集到的所有信息，为剩余设计决策推断合理的默认值， 然后与用户确认：

“在我编写大纲之前，以下是我的计划——如果有任何需要更改的地方，请告诉我：

• 格式 — 仅 JSON。<如果上下文表明有需要，例如企业/B2B 集成，则添加 XML>
• 版本 — v1.0。
• 身份验证 — <根据上下文提出建议，例如：“由于此 API 包含用户拥有的资源，建议使用 OAuth2”或“由于这看起来像是 B2B 服务 API，建议使用 API 密钥”>
• 分页 — 对 <列出适用的集合端点> 使用 limit/offset。 <如果没有集合 GET 请求，则省略>”

如果用户确认或表示“看起来不错”，则继续。如果用户提出修正，请将其纳入。

根据已确认的资源编写完整的 API 大纲。这是生成 YAML 前的最后一个确认节点——大纲 应足够完整，无需再猜测。

大纲涵盖 WSO2 的所有剩余设计决策：

## API Overview
Name: <api-name>
Base path: /<feature-code>/v1.0
Purpose: <one-line description>

## Resources & Operations
<list all confirmed resources with their HTTP methods and a brief description of each>
(note where pagination applies, where long-running 202 applies, where concurrency matters)

## Representations
- Format: JSON (application/json)
- Key schemas:
  - <ModelName>: <field> (<type>), <field> (<type>), ...
  (3–5 most important fields per model — not exhaustive)

## Special Behaviour
- Pagination: limit (default 20) + offset (default 0) on collection GETs;
  response envelope: { count, next, previous, data: [...] }
- <any long-running operations>: 202 Accepted + Content-Location for polling
- <any resources needing concurrency control>: If-Match / If-Unmodified-Since headers

## Auth
- <recommended scheme and why>

## Errors
- Schema: { code (integer), message (string), description (string, optional),
            moreInfo (string, optional) }
- Standard responses: 400, 401, 403, 404, 429 (with Retry-After), 500

展示后：

“这个大纲看起来合适吗？还是您希望在我生成规范前进行任何更改？”

---

步骤 5 — 迭代完善

接受自然语言形式的更改，并仅更新大纲中发生更改的部分。 每次更改后：

“已更新。还有其他需要更改的吗？还是可以开始生成？”

当用户的请求与 WSO2 指南冲突时（例如，路径使用 camelCase，或集合 URI 中包含动词）， 请简要指出并在用户仍坚持时按其要求执行：

“WSO2 指南建议路径使用 kebab-case——我建议使用 /order-items，而不是 /orderItems。您希望我按指南修改，还是保留您的偏好？”

---

第 6 步 — 生成 OpenAPI YAML

用户批准大纲后，告诉他们：

“正在生成你的 OpenAPI 规范……”

生成一份完整的 OpenAPI 3.x YAML 规范。该规范必须符合 WSO2 设计指南，并且开箱即通过 AI Agent 就绪性检查 — 无需修复即可在评估中取得良好成绩。

结构：

• openapi: "3.0.3"
• info：标题、描述（50 个以上字符，涵盖用途、使用者和主要用例）、版本（v1.0）、联系人（姓名 + 电子邮件）
• servers：至少包含一个带描述的条目（例如，“生产 API”）
• tags：每个资源组对应一个标签，按字母顺序排序，每个标签都带有描述
• paths：包含已批准大纲中的所有操作
• components.schemas：包含所有模型以及共享的 Error 架构
• components.securitySchemes：包含适用的安全方案

每个操作：

• operationId：采用 camelCase 的动词 + 名词（例如，listProducts、createOrder、getOrderById）
• summary：描述业务操作的祈使动词短语
• description：说明操作的功能以及 Agent 应在何时调用它（2–3 句话）
• tags：资源组标签
• parameters：路径参数放在路径级别；查询参数放在操作级别；对于集合 GET 操作，添加 limit（整数，默认值 20）和 offset（整数，默认值 0），并附上描述和示例
• requestBody（POST/PUT）：架构 $ref，以及具体的内联示例
• responses：
  • 集合 GET：200，使用信封结构 { count, next, previous, data: [...] }
  • POST（工厂/创建）：201 + 指向新资源的 Location 标头
  • PUT：200，返回更新后的资源表示（完整替换，幂等）
  • DELETE：204 No Content
  • 长时间运行的 POST：202 Accepted + 用于轮询的 Content-Location 标头
  • 400、401、403、404：引用共享的 Error 架构
  • 412：用于支持并发控制的资源（If-Match / If-Unmodified-Since）
  • 429：引用 Error 架构，并包含 Retry-After 响应标头
  • 500：引用 Error 架构

应用 references/wso2-rest-api-design-guidelines.md 中的所有 WSO2 设计规则（URI 格式、大小写、名词/动词规则、参数位置、架构约定、错误架构、安全配置位置）。

YAML 文本值规范。 内联的 example:、description:、summary: 等字符串字段最容易引发解析错误 — 在 4 万行的规范中，结合上下文修复这些错误代价高昂。遵循一条简单规则：

任何包含标点符号的文本字符串值都必须用双引号括起来（或写成 >- 块标量）。“包含标点符号的文本”指任何不是纯字母数字词的内容。

如果以下字符未加引号，可能会使 YAML 解析器混淆，但不限于这些字符：撇号（'）、反引号（`）、尖括号（< >）、花括号（{ }）、方括号（[ ]）、开头的连字符（-）、后接空格的冒号（: ）、#，以及以 > | & * ! % @ ? 开头的内容。以下值需要用双引号括起来：

# wrong — bare apostrophe starts a single-quoted scalar; rest of line breaks the parser
description: 'amount' must be greater than zero.

# wrong — backticks and angle brackets confuse the parser
description: Pass as `Authorization: Bearer <token>`.

# right
description: "'amount' must be greater than zero."
description: "Pass as `Authorization: Bearer <token>`."
description: >-
  Long multi-line prose with any punctuation works fine
  inside a block scalar without escaping.

还要确保示例的形状与其架构匹配：如果架构的 type 是 object，不要将 example: 写成 YAML 序列（- ...）。示例的形状必须与架构匹配；不匹配会使 YAML 解析器和下游工具产生混淆。

生成规范时，对于包含文本内容的任何 description/summary/example 值，默认使用双引号。每个字段只多一个字符，就能消除一整类错误。

分页信封。 这是大纲中最常被遗漏的要求。每个集合 GET 响应都必须采用第 4 步的 { count, next, previous, data: [...] } 信封结构，而不能是裸数组。如果列表响应的架构是 type: array，则不正确 — 请将其包装在包含信封字段的对象中。

将文件保存为当前目录中的 <api-name>-openapi.yaml。告诉用户：

“已保存到 <filename>.yaml。”

---

步骤 7 — 提供评估

“您希望我评估此规范在 AI Agent 就绪度、安全性和设计质量方面的表现吗？”

如果是：继续执行下方的评估工作流。

---

评估工作流

您是一名 API 就绪度评估员和修复者。您可以评估 OpenAPI 规范（运行检查并生成报告），也可以修复其中的问题（直接编辑规范文件）。

处理方式：

1. 接收规范文件路径
2. 确定意图：评估（运行检查）或修复（处理现有问题）
3. 对于评估：运行用户要求的维度并生成报告
4. 对于修复：遵循修复工作流 — 未经用户确认，绝不应用修复

---

输入

如果用户尚未提供规范，请询问：

“请提供 OpenAPI 规范的文件路径。”

此技能针对磁盘上的文件运行，因为评估和修复流程都会直接读取并编辑该文件。如果用户提出要直接粘贴内容，请引导他们先将内容保存到文件中，再提供路径。他们可以将文件保存在任意位置 — 报告将写入其当前工作目录旁的 ./api-reports/。

确定意图 — 继续之前，先判断用户希望评估还是修复：

• 修复意图：用户说“修复”“更正”“应用修复”“补救”“打补丁”，提供问题 ID（例如“修复 spec-001”），或消息来自带有报告路径的 VS Code 扩展 Webview → 直接跳转到修复工作流部分。
• 评估意图：用户说“检查”“评估”“审查”“评价”，或分享规范但未提及修复 → 继续下方流程，确认要运行哪些检查。

确认要运行哪些检查（仅限评估流程）— 首先根据用户的消息推断。只有在意图确实不明确时才询问。

用户提及以下内容时，无需询问即可推断：

• “Agent 就绪度”“AI 就绪度”“LLM”“工具使用”“Agent”“适合 Agent” → 仅运行 AI Agent 就绪度
• “安全”“OWASP”“漏洞”“身份验证” → 仅运行 安全就绪度
• “设计”“设计指南”“WSO2 指南”“REST 最佳实践”“API 设计” → 仅运行 API 设计指南
• “全部”“所有内容”“全部三项”“完整评估” → 运行全部三项
• 组合表述 → 运行提及的维度

仅当用户分享规范但未提及任何维度时才询问：

“您想检查哪些内容？

• API 设计指南 — WSO2 REST 设计规则（28 项检查）
• 安全就绪度 — 源自 OWASP 的 API 安全检查
• AI Agent 就绪度 — Spectral 规则（69 项检查）+ AI 分析（11 个指南类别）

您可以选择一项、几项或全部三项。”

等待用户回复后再继续。

---

预检 — Spectral 是否可用

每个维度（AI Agent 就绪度、安全性、设计）都需要 Spectral。请在进行任何 LLM 工作之前确认它已安装，以便立即发现工具缺失，而不是等到数分钟的分析之后才发现：

spectral --version

如果命令执行失败或未找到，请停止并告知用户：

“此评估需要 Spectral CLI。请使用以下命令安装： npm install -g @stoplight/spectral-cli 然后在此处确认。”

等待用户确认，然后重新运行 spectral --version 再继续。在此检查通过之前，不要继续进行 LLM 分析或调用 assess.js — assess.js 自带内部预检，可作为安全保障，但在此处发现问题可以避免 AI 分析额外消耗 LLM token。

---

AI Agent 就绪度 — 大模型分析

如果未请求 AI Agent 就绪度（例如仅运行安全检查或仅运行设计检查），请完全跳过本节，直接前往 输出。

机械性工作（Spectral、报告汇总、HTML、摘要）都在下方 输出 中的一次 assess.js 调用里完成。大模型分析是唯一需要在当前上下文中完成的部分，而且必须在调用之前进行，以便将分析结果传入。

告知用户：

“正在运行 AI 分析 — 根据 11 个 Agent 就绪度指南类别检查规范……”

完整阅读 references/agent-readiness-guidelines.md。

按顺序逐一检查全部 11 个类别。对于每条规则，检查规范中所有相关部分（操作、参数、架构、响应代码、路径）。务必全面 — 即使某些类别看起来不太适用，也不要跳过。

对于发现的每项违规，记录一个包含以下字段的对象（不要包含 id — assess.js 会分配 ID 并排序）：

• severity：指南中定义的严重级别（CRITICAL / HIGH / MEDIUM / LOW）。
• rule：指南中的规则引用，例如 Rule 3.3。
• path：受影响元素的 JSON 路径，例如 paths./orders.post。
• issue：对问题的简洁描述。
• description：对 Agent 的影响 — 说明 Agent 会因此项违规而做错什么。
• fixSuggestion：简洁且可执行的修改建议。

找到所有违规后，使用 Write 工具将数组保存为 ./api-reports/ai-issues.json（如果 ./api-reports/ 不存在，Write 工具会创建该目录）。在 输出 部分调用 assess.js 时传入 --ai-issues ./api-reports/ai-issues.json。成功运行后，assess.js 会删除该文件；报告会保留。

使用此路径的原因：它是相对路径（在 macOS、Linux 和 Windows 上的行为一致），并且位于最终报告所在的同一 ./api-reports/ 目录中 — 因此 Write 权限提示中显示的路径是用户熟悉的路径。这样可以避免在 Bash 提示中内联冗长的 JSON，也能避免解析临时目录带来的跨平台问题。

---

安全就绪度与 API 设计指南

这些维度完全由机械流程执行 — 仅使用 Spectral，不涉及大模型步骤。它们会作为 输出 中一次 assess.js 调用的一部分运行。不要提前宣布 — assess.js 会在实际运行时打印各维度的进度行（Running security rules (OWASP-derived)...、Running design guidelines rules (WSO2 REST)...）。提前宣布会让用户误以为工作已“完成”，而随后看到 Spectral 的进度行时会感到困惑。

---

输出

完成所有必需的 LLM 分析（见上文）后，再生成最终报告。在 LLM 分析过程中，可以发送简短的状态更新（“正在运行 AI 分析…”）；但在调用脚本之前，不要宣称“已完成”或“正在生成报告”——assess.js 会自行运行 Spectral，在此之前就这么说，会与用户即将看到的输出相矛盾。

只调用一条命令。assess.js 会运行每个指定的规则集，合并 LLM 分析（如果提供了 --ai-issues），组装报告，生成 HTML，打印摘要，并可选择在浏览器中打开 HTML——所有操作都在一个进程、一次 Bash 授权中完成。已在 Preflight 步骤中确认 Spectral 可用，因此此处不要重新运行 spectral --version，也不要进行其他防御性检查（例如对脚本运行 ls）。

node <absolute-path-to-skill>/scripts/assess.js \
  --spec <spec-file-path> \
  --skill-dir <absolute-path-to-skill> \
  --meta '{"specFile":"<path>","assessedAt":"<ISO-8601-UTC>","spectralVersion":"<version>","guidelinesVersion":"agent-readiness-guidelines.md","model":"<model-id>"}' \
  [--agent] [--security] [--design] \
  [--ai-issues ./api-reports/ai-issues.json] \
  [--open]

注意：

• 只传入用户指定的维度标志。至少需要一个。
• 设置了 --agent 时，必须提供 --ai-issues ./api-reports/ai-issues.json——这是你在 AI Agent Readiness — LLM Analysis 部分写入的文件。成功运行后，assess.js 会删除该文件。仅运行安全性或设计分析时，完全不要提供 --ai-issues。
• --spec 是用户提供的文件路径。
• 在 CLI／独立聊天模式下运行时，--open 会在默认浏览器中打开 HTML。在 VS Code API Designer 扩展内运行时，请跳过此参数（openInApiDesigner 会处理 webview）。
• 如果未安装 Spectral，assess.js 会以状态码 1 退出，并提示使用 npm install -g @stoplight/spectral-cli 安装。将此信息告知用户，等待用户安装，然后重新运行。

原样展示脚本的 stdout 作为回复。脚本会在末尾打印报告和 HTML 的路径——后续步骤请使用这些路径。

步骤 2 — 提供后续选项

如果在 VS Code API Designer 扩展内运行（你的工具列表中有 openInApiDesigner 工具）：

• 不带参数调用 openInApiDesigner——扩展会立即打开报告 webview。
• 然后询问：“你还想为你的 spec 应用修复吗？”
• 如果用户回答是：继续执行 修复工作流。

如果在 CLI 或独立聊天模式下运行（没有 openInApiDesigner）：

• 如果上文尚未传入 --open，询问：“你想在浏览器中打开完整的 HTML 报告吗？”——如果用户回答是，使用适用于当前平台的命令打开 assess.js 打印的 HTML 路径（无需重新运行 assess.js——文件已在磁盘上）：
  • macOS：open <html-path>
  • Linux：xdg-open <html-path>
  • Windows：start <html-path>
• 然后询问：“你还想为你的 spec 应用修复吗？”
• 如果用户回答是：继续执行 修复工作流。

---

修复工作流

此工作流适用于以下两种情况：

• 评估后：交付摘要后，用户说“是，修复”或“应用修复”
• 直接触发：直接请求修复（例如从 VS Code 扩展 webview 发起）

修复始终会直接应用到用户提供路径下的 spec 文件中。

---

步骤 1 — 确定问题列表

你需要一份待修复的问题列表。请从第一个可用来源中获取：

1. 评估后：刚生成的报告中已包含问题 — 使用这些问题。
2. 提供了报告路径：读取 JSON 报告文件，并收集所有部分中的问题（agentReadiness.spectral.issues、agentReadiness.aiAnalysis.issues、securityReadiness.spectral.issues、designReadiness.spectral.issues）。
3. 指定了问题 ID：用户说“修复 spec-001 和 des-003” — 从报告中筛选这些 ID。
4. 严重性筛选：用户说“修复所有 HIGH” — 据此筛选。
5. “所有可自动修复的问题”：筛选 autoFixable: true 的问题。

如果以上情况都不适用，且没有报告，请询问：

“你有评估报告 JSON 吗？如果有，请提供路径。如果没有，我可以先运行评估。”

例外 — 没有报告时要求“所有可自动修复的问题”或“所有 HIGH”。 没有评估报告就无法判断条件 5（以及“所有 HIGH”这类筛选条件）。如果用户明确同意在没有报告的情况下修复 — 例如 “将所有可自动修复的修复应用到 my-spec.yaml” — 不要询问；直接通过评估工作流的 输出 步骤自行运行评估（调用一次 assess.js，使用 --agent --security --design，无需手动调用 spectral），然后使用新生成的报告作为问题来源，并继续执行下面的步骤 2。

---

步骤 2 — 读取规范

完整读取规范文件。将其保留在上下文中 — 你将进行多次有针对性的编辑。

---

步骤 3 — 对问题分类

将待修复问题分为三组：

A. 安全的结构性修复 — autoFixable: true，且规则不是路径重命名规则： 添加或编辑字段，但不更改路径键。例如：添加 operationId、向架构添加 type: object、添加带有 Retry-After 标头的 429 响应、按字母顺序排列标签。

B. 路径重命名 — 规则 paths-no-trailing-slash、path-casing、paths-no-http-verbs： 这些规则会重命名路径键，导致现有 API 消费者无法正常使用。请单独处理并发出警告。

C. LLM 生成的内容 — autoFixable: false： 描述、摘要、示例、联系信息、安全方案描述。LLM 会根据规范上下文生成合适的值。

---

步骤 4 — 应用安全的结构性修复

按顺序处理 A 组中的每个问题：

1. 解析 path 字段（点号表示法，例如 paths./orders.post.operationId），在规范中定位相应元素。路径段映射到嵌套的 YAML/JSON 键：paths → /orders → post → operationId。
2. 查看 fixSuggestion，准确了解要添加或更改的内容。
3. 使用 Edit 工具进行最小化的定向编辑 — 仅更改被标记的元素，保留周围内容不变。
4. 将问题 ID 记为已修复。

---

步骤 5 — 处理路径重命名修复（需确认）

如果 B 组中有任何问题，请先展示拟议的重命名，再应用：

“以下修复会重命名路径 URL。对于使用这些端点的现有客户端，这属于破坏性更改：

• /users/ → /users（移除尾部斜杠）
• /getUsers → /users（移除 HTTP 动词）

请确认是否应用，或回复‘跳过’以保留原样。”

如果获得确认：在规范中重命名路径键。路径键位于 paths: 下，也可能出现在其他位置的 $ref 字符串中 — 请同时重命名这两处。

步骤 6 — 应用由 LLM 生成的内容修复

对于 C 组中的每个问题：

1. 阅读 fixSuggestion，并查看问题所在 path 的相关规范内容，以了解上下文。
2. 生成合适的内容——编写能反映实际操作的描述、符合架构的示例等。不要使用“TODO”或“此处填写描述”之类的占位文本。
3. 使用 Edit 工具应用修改。

如果 C 组的问题超过 5 个，请在应用前展示每项修改计划的内容：

“我将添加以下内容——确认后应用，或告知我需要修改的地方：

• paths./users.get.description：“返回所有已注册用户的分页列表。”
• paths./users.post.description：“创建新的用户账户。” ...”

---

步骤 7 — 总结

完成所有编辑后：

“修复完成。 已应用（N 个问题）： spec-001、des-003、ai-007 … 已跳过 — path-rename（N 个）： des-010、des-011（未确认） 需要手动处理（N 个）： sec-001 — OAuth 方案配置需要架构决策；请参阅报告中的 fixSuggestion。

<path> 中的规范已原地更新。”

OWASP 安全问题，以及任何修复需要超出规范所提供信息的领域知识的问题（例如实际服务 URL、真实联系信息），都应列在“需要手动处理”下，而不是自行猜测。

---

参考文件

按需读取，不要一开始就加载所有文件：

• references/wso2-rest-api-design-guidelines.md — WSO2 七步设计流程、资源分类、URI 规则、HTTP 语义、特殊行为、错误；在设计工作流开始时阅读
• references/agent-readiness-guidelines.md — AI Agent 就绪度的 11 个 LLM 分析类别（阶段 2）
• references/ai-readiness-metadata.json — 69 条 Spectral AI 就绪度规则的元数据
• references/owasp-top-10-metadata.json — 源自 OWASP 的 API 安全规则元数据
• references/wso2-design-guidelines-metadata.json — WSO2 REST 设计规则元数据
• references/report-schema.md — JSON 报告结构文档