openapi-spec-generation

本技能为 OpenAPI 3.1 规范的生命周期管理提供了强大的框架，确保您的 RESTful API 保持良好的文档记录并符合既定合约。它专为软件工程师、API 架构师与开发人员设计，协助您在开发周期中平衡速度与准确性。无论您是采用设计优先 (Design-First) 策略启动新项目，还是利用代码优先 (Code-First) 策略完善现有代码库，本工具都能提供必要的模板与结构指导，以维护清晰且机器可读的 API 定义。

• 全面支持 OpenAPI 3.1.0 标准，包括复杂的组件 (components)、安全机制 (security schemes) 与高级模式 (schemas)。

• 为实施设计优先、代码优先及混合开发工作流程提供战略指导。

• 支持 API 文档自动化模板生成，涵盖验证机制、速率限制与服务器定义。

• 提供详细的路径与操作管理，包含 HTTP 动词、参数定义与标准化的错误响应模式。

• 通过准备符合自动化客户端 SDK 生成与交互式 API 文档门户需求的规范，促进下游无缝集成。

• 针对新 API 使用设计优先方法，确保在编写后端代码之前与团队达成共识。

• 利用代码优先方法，从控制器与路由定义中提取元数据，确保文档内容真实反映代码。

• 针对持续演进的服务采用混合方法，结合手动注释与自动生成的规范片段。

• 通过引用全局组件来处理常见错误（如 400 Bad Request, 401 Unauthorized, 429 Rate Limited），确保错误处理的一致性。

• 输入通常包含 API 端点详细信息、模型结构与安全需求；输出为符合业界标准且基于 YAML 或 JSON 的有效 OpenAPI 规范。