用途:校验 API 规范与契约,在交付给消费者之前发现不完整 schema、未文档化端点、命名不一致与破坏性变更。
主要能力:对照 OpenAPI 3.0/3.1、JSON Schema Draft 2020-12、GraphQL SDL 标准做结构校验与 lint;检查命名约定、必填描述与示例值;验证 schema 完整性(请求 schema、各响应状态码 schema、$ref 可解析);检查安全方案覆盖;对比上一版本检测破坏性变更(删除端点、删除必填字段、类型变化、枚举收窄);校验分页参数、错误响应封装与日期格式一致性;按 error/warning/info 分级输出 file:line 定位的报告。
前置条件:OpenAPI(YAML/JSON)或 GraphQL SDL 文件;lint 工具 Spectral、graphql-schema-linter 或 ajv-cli;schema 文件的版本控制;CI 流水线;oasdiff 或 openapi-diff。
使用方式:用 Glob 定位所有 API 规范文件;运行结构校验确认符合声明标准且语法有效;应用 Spectral 规则;检查完整性与安全方案;与上一发布版本对比检测破坏性变更;校验跨端点一致性;生成报告。输出包括 reports/schema-validation.json、reports/schema-validation.md、reports/breaking-changes.md、.spectral.yaml、scripts/validate-schema.sh 与 reports/schema-coverage.md。
适用场景:提交前 schema lint(pre-commit 钩子)、PR 上的破坏性变更 CI 门禁、端点文档完整性审计。
限制:需要具备规范文件与相应工具;破坏性变更检测依赖版本控制中的上一版本;具体安装与运行命令、收费情况暂未提供。