《OpenAPI 规范验证器与 Linter》

为什么需要它

OpenAPI 文档越写越大之后，问题往往不是「能不能解析」，而是「能不能交付」。一个接口缺了 description、两个路径的命名风格不一致（getUserInfo 和 get-user-detail 混用）、安全方案声明了却没人引用——这些错误不会让 Swagger UI 直接崩溃，但会让调用方困惑、让安全评审返工。手工 review 一遍几百个端点的 YAML，耗时且容易漏掉同类问题。

技能如何工作

该技能把校验拆成两个层次，而不是简单跑一遍格式检查：

• 语法与结构解析：底层使用 @readme/openapi-parser，负责读取 OpenAPI 3.0/3.1 文档，处理 $ref 引用展开与格式错误，先把「文档能不能被正确解析」这件事独立出来。
• 规则化 Lint：基于 Spectral 的可配置规则集，针对 OpenAPI、Arazzo 或 AsyncAPI 等规范加载预定义规则集，并允许团队自定义 .spectral.yaml 补充规则。
• 重点检查项：

- 接口与字段缺失 description 的情况
- 命名约定不统一，如标签大小写、参数命名风格漂移
- 安全方案（security scheme）声明后未被任何操作引用，或存在明显缺口

使用时，在项目根目录准备一份 Spectral 配置文件即可开始运行检查，扫描结果按文件和行号输出，方便直接定位修改。

适用边界

• 它解决的是「规范一致性」和「常见遗漏」问题，不会自动修复代码，也不会替你写好业务描述文案。
• 自定义规则集的严格程度取决于团队配置，规则过严会引入噪音，过松则只覆盖表面问题。
• Spectral 与解析器对 OpenAPI 3.1 的支持随版本演进，遇到边缘特性（如 Webhooks 的高级写法）时，仍需结合人工判断。