openapi-spec-generation

概述

什么是 openapi-spec-generation？

openapi-spec-generation 是一款实用技能，适合需要生成、维护和验证 RESTful API 的 OpenAPI 3.1 规范的开发者和 API 团队。它支持代码优先和设计优先两种工作流程，适用于新建 API 项目、现有代码库以及不断演进的 API 合同。该技能帮助您创建准确的 API 文档，验证实现，并从 OpenAPI 规范生成客户端 SDK。

谁适合使用此技能？

• 设计新 RESTful API 的 API 开发者和架构师
• 维护或编写现有 API 文档的团队
• 需要确保 API 合同合规或自动化生成 SDK/文档的任何人

它解决了哪些问题

• 简化从代码或设计文档创建 OpenAPI 3.1 规范的流程
• 方便 API 文档编写和合同验证
• 支持自动生成客户端 SDK 和搭建 API 门户

使用方法

安装步骤

1. 添加技能：
   使用以下命令安装 openapi-spec-generation：

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

2. 浏览关键文件：

   • 从 SKILL.md 开始，了解概览和使用模式。
   • 查看 references/code-first-and-tooling.md，了解代码优先生成示例（如 Python/FastAPI 或 TypeScript/tsoa）。
   • 查阅 references/ 文件夹，获取高级模式和模板。

3. 适配您的工作流程：

   • 使用设计优先方法，在编码前编写规范，适合新 API 或严格的合同优先开发。
   • 使用代码优先方法，从带注释的代码生成规范，适合现有 API 或快速原型开发。
   • 随着 API 演进，结合两种方法实现混合工作流程。

示例用例

• 设计优先： 先用 YAML 草拟 OpenAPI 3.1 规范，再实现 API。
• 代码优先： 使用 FastAPI（Python）等框架，从代码注释自动生成 OpenAPI 规范。
• 验证： 确保 API 实现符合 OpenAPI 合同，保证集成可靠。
• SDK 生成： 利用规范生成多语言客户端库。

常见问题

openapi-spec-generation 实际做什么？

openapi-spec-generation 提供生成和维护 OpenAPI 3.1 规范的模式和模板，支持代码优先和设计优先两种方法。它帮助自动化文档编写、验证和 SDK 生成，适用于 RESTful API。

安装后如何开始？

首先阅读 SKILL.md 了解整体概览。对于代码优先工作流程，请参阅 references/code-first-and-tooling.md，获取使用 FastAPI 等框架的实用示例。根据项目需求调整模板和模式。

这个技能适合非 REST API 吗？

openapi-spec-generation 专注于 RESTful API 和 OpenAPI 3.1。对于其他 API 模式（如 GraphQL），此技能可能不太适用。

可以同时用于新旧 API 吗？

可以。该技能支持设计优先（新 API）和代码优先（现有 API）工作流程，也支持混合方法。

哪里能找到更多示例或模板？

请查看 references/ 文件夹，特别是 references/code-first-and-tooling.md，获取高级用法和示例代码。

如何验证我的 API 是否符合规范？

虽然该技能提供了模式和模板，您可以结合标准 OpenAPI 工具（如 Swagger、Redoc 或 openapi-generator）进行验证和 SDK 生成。

打开文件标签浏览完整文件树，包括嵌套的参考资料和辅助脚本，以实现更深入的集成。