openapi-spec-generation

openapi-spec-generation skill 概览

openapi-spec-generation skill 能做什么

openapi-spec-generation skill 用经过验证的模式来帮助 agent 创建或完善 OpenAPI 3.1 API 规范，而不是靠临时拼凑的 prompt。它面向的是那些需要可实际落地的 API contract 的团队：用于文档、客户端 SDK 生成、校验和 API 治理，而不只是产出一份粗略的 YAML 草稿。

谁适合使用它

这个 skill 特别适合以下场景：

• 后端团队为现有 REST API 补齐和整理文档
• 平台团队统一多个服务之间的 contract 标准
• 从 code-first 框架迁移到更清晰规范 spec 的开发者
• 正在为 SDK 生成、mock server 或 contract 检查做准备的团队

它关注的重点不是“OpenAPI 是什么”，而是“怎样更少踩坑地拿到一份完整、可信、可用的 spec”。

它真正解决的工作任务

大多数用户要的并不只是一个名为 openapi.yaml 的文件，而是一份足够好的 spec，能够：

• 描述真实的请求和响应结构
• 建模认证、错误、分页和通用 headers
• 支撑后续工具链使用
• 在 API 迭代时仍然保持可维护

openapi-spec-generation skill 的价值在于，它会把工作重点推向 OpenAPI 3.1 的结构、设计路径选择和具体模板，而不是停留在泛泛的 API 描述文字上。

这个 skill 的差异点

和普通的“帮我写一份 OpenAPI spec”提示相比，这个 skill 给 agent 提供了：

• 明确的 OpenAPI 3.1 框架
• 针对 design-first、code-first 和 hybrid 工作流的指导
• 可复用的完整规范模板
• 收录在 references/code-first-and-tooling.md 中的 code-first 示例

这也是为什么它特别适合 openapi-spec-generation for API Development 这类场景：团队既要衔接实现细节，又要保证 contract 质量。

安装前需要先判断什么

在采用 openapi-spec-generation skill 之前，先明确你的核心需求是：

• 根据产品需求起草一份新 contract
• 从现有代码中抽取 contract
• 把已有 spec 进一步收紧和补全

如果你的 API 高度偏 RPC 风格、事件驱动，或者本身不是 REST 导向，那么这个 skill 更适合做适配后使用，而不是直接照搬。

如何使用 openapi-spec-generation skill

openapi-spec-generation 的安装上下文

先安装父级 skill collection，然后在 agent 工作流中调用 openapi-spec-generation：

npx skills add https://github.com/wshobson/agents --skill openapi-spec-generation

这个 skill 位于 wshobson/agents 仓库中的 plugins/documentation-generation/skills/openapi-spec-generation。

建议先读这两个文件

为了最快上手，优先阅读：

1. plugins/documentation-generation/skills/openapi-spec-generation/SKILL.md
2. plugins/documentation-generation/skills/openapi-spec-generation/references/code-first-and-tooling.md

SKILL.md 负责说明主要范围和模板；参考文件则补充了更实操的 code-first 模式。如果你的 source of truth 是应用代码，这部分尤其值得先看。

先选对起步方式

这个 skill 支持三种很实用的入口方式：

• Design-first：最适合新 API，以及实现前先做 contract 评审的场景
• Code-first：最适合 API 已经存在，比如基于 FastAPI 等框架实现
• Hybrid：最适合代码已经有了，但你仍希望整理出一份更适合作为对外 contract 的版本

很多人低估了这一步对输出质量的影响。若跳过这一步，结果通常会变得空泛，或者内部前后不一致。

openapi-spec-generation skill 需要哪些输入

当你提供明确的 API 证据时，openapi-spec-generation usage 的效果会明显更好，例如：

• 路由列表，包括 methods 和 path params
• 请求与响应 JSON 示例
• 认证模型
• 分页方式
• 主要错误场景
• 实体 schema 或 validation models
• 环境/服务器 URLs
• 命名约定和版本规则

如果你只给一句“为我的用户 API 生成一个 spec”，那大概率只能得到一份模板味很重、后续还需要大量补 contract 细节的草稿。

如何把模糊目标改写成高质量 prompt

弱 prompt：

• “Generate an OpenAPI spec for a user service.”

更强的 prompt：

• “Use the openapi-spec-generation skill to create an OpenAPI 3.1 spec for a REST API with GET /users, POST /users, GET /users/{id}, and PATCH /users/{id}. Auth is bearer token. Users have id, email, name, status, and createdAt. Use cursor pagination on list endpoints, include standard 400/401/404/409 responses, model reusable schemas under components, and produce a clean spec suitable for SDK generation.”

更强的版本给了这个 skill 足够的结构信息，产出的就会是一份 contract，而不是占位性质的样板文本。

面向现有 API 的最佳工作流

针对现有服务，一个实用的 openapi-spec-generation guide 可以这样走：

1. 从代码或 router 定义中盘点所有 routes。
2. 提取请求模型、响应模型、枚举和值校验规则。
3. 判断框架自动生成的文档是作为 baseline，还是仅作参考。
4. 让这个 skill 将信息统一整理为 OpenAPI 3.1。
5. 审查是否缺少错误响应、认证细节、示例和 schema 复用。
6. 之后再用你自己的 validation 或 linting 工具做检查。

相比“凭印象一次性生成完整 spec”，这种流程通常更可靠。

面向新 API 的最佳工作流

对于新 API：

1. 先定义资源和操作。
2. 确定版本策略、认证方式和分页模式。
3. 让这个 skill 生成一份 design-first 的 spec，并带上可复用 components。
4. 在写代码前先检查命名一致性和错误模型。
5. 将确认后的 spec 作为实现 contract。

这正是这个 skill 发挥高杠杆价值的地方，因为 contract 层面的错误在代码还没落地之前修起来最便宜。

如何高效利用 code-first 参考文件

附带的 references/code-first-and-tooling.md 对 Python 或 TypeScript 生态尤其有帮助。它能让你更清楚地知道，好的 source material 应该长什么样：

• typed models
• enum 使用
• validation metadata
• 框架层面的 descriptions 和 tags
• server definitions

这很关键，因为 code-first 的 OpenAPI 生成质量，很大程度上取决于你的代码有没有把领域模型表达清楚。

一份好的输出通常应包含什么

一份合格的 openapi-spec-generation skill 输出通常应包含：

• openapi: 3.1.0
• 清晰的 info 元数据
• 真实可用的 servers
• 完整的 paths
• 可复用的 components.schemas
• security schemes
• 通用响应/错误处理
• 在歧义会影响接入时提供 examples

如果这些部分缺失，这份草稿通常还不能直接进入下游工具链。

常见的仓库阅读路径

如果你想在正式依赖这个 skill 之前先检查上游内容，建议按这个路径看：

• 先扫一遍 SKILL.md，了解它的 scope、结构和模板
• 再打开 references/code-first-and-tooling.md，看实现导向的示例
• 最后把这些示例和你所用框架、当前 API 成熟度对照起来

这个仓库本身比较轻量，所以核心价值不在自动化脚本，而在 prompt scaffolding 和示例质量。

提升输出质量的实用建议

• 提供真实字段名，不要用占位符。
• 明确哪些字段允许为 null。
• 列出你实际使用的错误码。
• 说明 ID 是 UUID、整数，还是 opaque string。
• 写清楚列表接口使用的是 cursor、page/size，还是 offset/limit 分页。
• 告诉这个 skill 哪些 schemas 应该在多个 endpoints 间复用。

这些细节能显著减少后续清理和返工。

openapi-spec-generation skill 常见问题

openapi-spec-generation 适合新手吗？

适合，前提是你已经理解自己的 API。这个 skill 能帮助你把 spec 组织起来，但它不能替代你对 endpoints、认证和数据模型的了解。如果是手头连 API inventory 都没有的新手，往往还是很难提供足够的源输入。

它真的比普通 OpenAPI prompt 更好吗？

通常是的。openapi-spec-generation skill 比通用 prompt 的起点更好，因为它把重点放在 OpenAPI 3.1、设计路径选择和实用模板上。差异不在“更有创意”，而在“更完整、更一致”。

它能直接从代码自动生成 spec 吗？

不能，至少不是那种自动扫描整个仓库的方式。它提供的是 code-first generation 的模式和示例，尤其体现在参考文件里；但你仍然需要把相关代码上下文或提取好的 endpoint 细节提供给 agent。

什么情况下这个 skill 不太适合？

如果满足以下情况，它就不是最强选择：

• 你的 API 并不接近 REST 风格
• 你需要从大型代码库中全自动抽取
• 你的主要问题是运行时测试，而不是 contract 创建
• 你更需要 framework-specific tooling setup，而不是 spec 编写指导

在这些场景下，专用生成器或框架原生工具，往往更适合作为主路径。

可以用它来维护已有 spec 吗？

可以。openapi-spec-generation 很适合把不完整的 spec 收紧、对齐到 OpenAPI 3.1，并补上缺失的可复用 components、responses 和文档结构。

它适合用于 SDK 生成工作流吗？

适合，但前提是你要先认真审查结果。SDK 生成对 schema 质量、enum 建模、operation IDs、auth 定义以及响应一致性都很敏感。这个 skill 能帮你把这些部分先搭起来，但最终验证仍然是你的责任。

如何改进 openapi-spec-generation skill 的使用效果

给 openapi-spec-generation skill 提供 contract 级输入

提升 openapi-spec-generation 输出质量最快的方法，是不要再停留在 feature 层面提问，而是直接以 contract 层面来描述。应尽量提供：

• 精确的 endpoints
• 必填与可选字段
• enum 值
• 示例 payloads
• status codes
• 认证规则
• 可复用对象结构

这样输出就会从“长得像 spec 的文字”更接近真正可用于生产的内容。

明确要求补上缺失章节

很多首稿都会漏掉对实际落地很关键的内容。你可以直接要求这个 skill 补上：

• security schemes
• 分页参数
• 错误响应 schema
• operation IDs
• 可复用 request bodies
• tags 和 descriptions
• 容易混淆字段的 examples

这类显式要求很有价值，因为泛化生成的 spec 草稿通常会在这些方面写得不够。

在 code-first 工作流里避免 schema drift

如果你是在现有服务上使用 openapi-spec-generation for API Development，最大的风险通常是 schema drift。要降低这个风险，最好补充：

• 当前模型定义
• validation constraints
• route handlers 或 controller signatures
• 实现与文档之间已知的不一致点

否则，这个 skill 可能会产出一份“编辑上更漂亮”的 contract，但它未必和真实 API 完全一致；从文档角度看可能更好，从运维和集成角度看却有风险。

分轮迭代，不要一口气提一个巨型请求

更好的流程通常是：

1. 先生成骨架
2. 再细化 schemas
3. 再补 auth 和 errors
4. 再添加 examples
5. 最后统一命名和复用方式

对中等规模 API 来说，这种分阶段流程通常比一次性的大 prompt 更稳。

留意常见失败模式

首轮输出中常见的问题包括：

• 描述太泛，缺少实际操作价值
• 缺少错误模型
• paths 和 schemas 命名不一致
• 请求校验约束描述不足
• 没有明确区分 create、update 和 read models
• examples 与 schema constraints 对不上

这些问题都能修，但前提是你要结合真实 API 行为去审查。

把参考文件当成 prompt 的一部分

在实践里，提升 openapi-spec-generation guide 效果的一个简单办法，是直接告诉 agent 参考 references/code-first-and-tooling.md 中展示的结构和细节层级，尤其是：

• typed schemas
• enum 处理
• validation metadata
• server definitions
• model descriptions

这会比一句空泛的“写完整一点”更能给 agent 清晰模式。

生成后一定要做验证

即使草稿质量不错，也应该继续走你平时的 OpenAPI validators、linters 和下游 generators。这个 skill 的作用是帮你拿到更好的第一版，而不是取代验证流程。尤其当输出要用于 docs portal、code generation 或 contract testing 时，这一步更不能省。

先缩小范围，再提升 openapi-spec-generation skill 输出质量

如果第一次结果很乱，就把请求范围收窄：

• 一次只做一个 resource
• 一次只做一组 paths
• 一次只做一类 schemas

然后把审过的部分再合并起来。对很多团队来说，这是在生产工作中使用 openapi-spec-generation usage 最稳妥、成功率最高的方式。