openapi-spec-generator

OpenAPI Spec Generator 是一款专为工程团队设计的技术技能，旨在架起后端开发与 API 文档之间的桥梁。它能自动生成符合行业标准的 OpenAPI 3.0 和 3.1 规范，确保 API 合约的准确性与可读性。此工具非常适合优先采用 API 设计先行策略或需要维护现有代码与文档一致性的软件工程师、后端开发者及系统架构师。通过直接整合到开发工作流中，它消除了手动维护文档的需求，从而减少了 API 逻辑与接口定义之间的偏差。

• 自动从 FastAPI、NestJS 和 Express 的框架特有装饰器与模型生成 OpenAPI 规范。

• 支持手动编写完整的 YAML 规范，包含 Info、Servers、Paths、Components（架构/参数）以及 Security（Bearer, OAuth2, API Key）。

• 促进强大的 TypeScript 和 Python API 客户端 SDK 的自动生成，简化前端与跨服务整合。

• 提供模拟服务器的快速设置，实现前后端开发周期的解耦。

• 实现与 Swagger UI、ReDoc 和 Stoplight 等交互式文档套件的无缝整合。

• 支持进阶 API 实践，如合约测试、请求/响应验证以及包含请求/响应范例的复杂架构定义。

• 当启动新的 API 先行设计并在实现前定义接口，或为现有的 RESTful 服务补充文档时，请使用此技能。

• 输入通常包括源代码文件、Pydantic 模型或结构化的 YAML 组件定义；输出为生产级的 JSON/YAML 规范文件或生成的客户端库。

• 请确保所有安全架构均在组件部分明确定义，以正确记录身份验证要求。

• 利用提供的 FastAPI 和 NestJS 模板，确保装饰器与注解能正确映射到 OpenAPI 定义。

• 对于合约测试，请将生成的规范作为单一事实来源，用于跨集成测试验证请求/响应负载。

• 生成器严格遵循 OpenAPI 3.0/3.1 标准，支持复杂的嵌套对象结构、递归架构以及细粒度的验证规则，例如 minLength、maxLength 和格式约束。