OpenAPI 验证器
检查 YAML 或 JSON 格式的 OpenAPI 3.0、3.1、3.2 或 Swagger 2.0 文档,并获取其端点和 Schema 摘要。验证器会检查必填字段、路径模板与路径参数是否匹配、参数位置、响应代码、重复的 operation ID 以及所有本地 $ref,并列出每个问题及其位置。
常见问题
验证器会检查什么?
它会检查 openapi 或 swagger 版本、info.title 和 info.version、路径是否以斜杠开头、路径中的每个 {parameter} 是否都有对应的必填路径参数(反之亦然)、参数名称和位置、响应状态代码和描述、重复参数、重复 operationId 值,以及每个本地 $ref 是否指向文档中的内容。
这是对规范进行完整的 JSON Schema 验证吗?
不是。它会检查上述结构规则,这些规则可以发现手写文档中的大多数错误,但不会根据官方元 Schema 验证每个字段,也不会检查 Schema 的内容。
摘要会显示哪些内容?
规范和 API 版本、标题、包含每个端点及其方法、路径、operationId、摘要和响应代码的表格,以及 components.schemas 下的 Schema 名称;对于 Swagger 2.0,则显示 definitions 下的名称。
会跟踪外部引用吗?
不会。不会获取或报告对其他文件或 URL 的引用。只有以 # 开头的引用才会在粘贴的文档中解析。
错误和警告有什么区别?
错误表示违反了规范规则,例如缺少响应描述,或路径参数未声明。警告指出的是允许但通常并非本意的情况,例如带有请求正文的 GET 操作,或没有任何 operationId 的文档。
OpenAPI 3.1 会改变必填项吗?
会。在 OpenAPI 3.1 和 3.2 中,操作不再需要 responses 对象;文档也可以包含 webhooks 或 components,而不是 paths。若 openapi 字段以 3.1 或 3.2 开头,验证器就会应用这些规则。