# 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 开头，验证器就会应用这些规则。

在这里投放广告？

[给我们发邮件](mailto:hi@dennn.is?subject=%E5%9C%A8%20OneClick%20Pro%20%E4%B8%8A%E6%8A%95%E6%94%BE%E5%B9%BF%E5%91%8A)

[广告 通过一个 MCP 服务器为你的 AI 代理提供 433 种工具。](https://multitaskai.com/zh/?ref=oneclickpro)
