OpenAPI 规范参考索引器

核心问题

OpenAPI 3.x 文档规模变大后，常见问题是团队对同一规范产生不同理解：路径参数、响应模型、安全方案分散在各处，接口文档、代码生成与网关配置之间难以对齐。手动整理 endpoint 目录既费时，也容易遗漏 schema 引用与鉴权配置。

工作原理

该技能以 swagger-parser 和 Redocly CLI 为基础，对 OpenAPI 3.x 文档做解析与交叉引用。其核心流程包括：

• 解析入口：读取 openapi 字段，定位文档的元数据与版本信息。
• Schema 解析：展开 $ref 引用，将分散的定义合并为可查询的模型图。
• 端点目录构建：遍历 paths，提取 HTTP 方法、参数、响应码与描述，形成可检索接口清单。
• 认证映射：解析 components.securitySchemes，把 oauth2 流程、apiKey 位置等配置映射到具体 endpoint。
• 生成元数据：输出可被 SDK 工具链消费的结构化信息，供后续代码生成使用。

适用边界与注意点

它不替代规范评审，也不自动修复设计缺陷。若源文档引用缺失或版本不兼容，解析可能失败，需要先修复文档。使用前应确认规范来源与工具链版本；涉及敏感数据时建议在隔离环境验证。