OpenAPI 规范校验器
将以下提示词粘贴到你的 AI 对话框中:
请根据 https://skillhub.cn/install/skillhub.md,安装 @user_8ee65e73/openapi-spec-validator。
技能介绍
解决哪些具体问题
很多团队在维护 OpenAPI 文档时依赖人工审查,常见的问题包括路径键大小写错误、数据模型声明与内联定义不一致、操作缺少合法描述或文档版本与本地校验规范不兼容。手工检查容易漏掉细节,尤其当服务数量增加、文档更新频繁时,错误往往直到集成阶段才被发现。该技能用于替代人工逐字段核对,在开发过程中快速给出校验结论,避免带着问题进入生成、发布或联调环节。
核心能力与关键步骤
- 规范化解析:读取接口文档中的路径对象与数据模型,统一处理内联结构与引用关系。
- 逐项校验:检查结构是否完整,字段类型是否明确,描述是否缺失,
operations下的语义是否符合校验约定。 - 结果输出:汇总错误条目,标注问题位置与可能原因,便于直接定位修复。
适用边界与注意点
- 适合集成到开发脚本或代码审查流程中,作为接口文档质量门禁。
- 该技能是规范校验工具,不具备请求模拟、端点运行测试或路径覆盖分析能力。
- 对未按指定 OpenAPI 版本编写的文档需要先完成格式确认。
- 校验结果只反映静态一致性,实际请求异常仍需通过集成测试验证。
使用场景
- 检查接口文档中路径键与数据模型是否一致
- 审查 operations 下的字段描述是否符合规范
- 将校验执行嵌入 CI 流程作为文档质量门禁
适合人员
- 后端工程师:需要确认接口文档可被标准工具解析
- API 维护者:要定位文档中缺失或格式错误的字段
- DevOps 工程师:需要在合并前自动校验接口规范