OpenAPI 规范参考生成器

要解决的具体问题

当团队维护 OpenAPI 3.x 规范文件（.yaml 或 .json）时，手动整理 API 参考文档不仅耗时，还容易因格式不一致导致信息偏差。开发者往往需要快速将规范转化为可浏览、可检索的文档，同时保留静态 HTML 用于部署，或提取 Postman 集合用于接口测试。

技能如何工作

该技能通过两个核心工具实现转换：

• 解析层：基于 swagger-parser 读取并验证 OpenAPI 3.x 规范文件，确保语法正确性与结构完整性。
• 渲染层：调用 redoc-cli 生成交互式 HTML 文档，支持路径参数、请求示例与响应模型的可视化展示。
• 扩展输出：自动生成 Markdown 格式文档，并导出 Postman 集合（.json），可直接导入测试工具。

适用边界与注意点

• 规范版本限制：仅支持 OpenAPI 3.x，无法处理 Swagger 2.0 或更早版本。
• 静态内容依赖：生成的 HTML 为纯静态文件，若规范更新需重新运行技能。
• 测试功能缺失：Postman 集合仅提供请求模板，不包含实际执行或断言逻辑。
• 敏感场景需审核：因未提供自动安装说明，建议先审查上游项目再用于生产环境。