OpenAPI 验证器：检查 API 规范
支持 Swagger 2.0 和 OpenAPI 3.x 的 OpenAPI 验证器。粘贴 JSON 或 YAML 即可获得即时验证错误、警告和端点摘要。
什么是 OpenAPI 验证器？
OpenAPI 验证器是一款基于浏览器的工具，用于解析和验证 OpenAPI 3.x 和 Swagger 2.0 规范文件。粘贴 JSON 或 YAML spec，点击 Validate，几秒内即可看到 spec 是否结构有效、路径和操作的数量，以及对 SDK 生成器和开发者文档工具重要的缺失字段的警告列表。
该工具完全在浏览器中运行，使用按需加载的 @readme/openapi-parser 库。没有 spec 内容会发送到任何服务器。免费使用，无需帐户。
在将 spec 提交到版本控制之前、发布 API 文档之前，或在调试被 Swagger UI、Stoplight 或 SDK 生成器等下游工具拒绝的 spec 时使用它。
主要功能
- 支持 OpenAPI 3.x 和 Swagger 2.0：验证器接受两种格式。底层
@readme/openapi-parser库处理包括 OpenAPI 3.1 在内的两个规范版本。 - JSON 和 YAML 输入：工具先尝试 JSON.parse，失败后回退到
js-yaml解析 YAML。 - 带精确错误消息的结构验证：验证失败时，解析器的错误消息按换行符分割并逐条显示。
- Linting 警告：即使 spec 结构有效，工具也会检查三个常见质量问题：缺少
info.description、没有description和summary的操作、没有operationId的操作。 - 端点和操作计数：成功验证后，摘要磁贴显示 API 标题、版本字符串、总路径数和总操作数。
- 加载示例按钮：插入一个最小但完整的 OpenAPI 3.0 spec，包含一个
/usersGET 端点。 - 验证历史：之前的 spec 保存在浏览器的 IndexedDB 中（支持者功能）。
- 100% 客户端处理：解析器和验证器在浏览器中运行。
如何使用 OpenAPI 验证器
第 1 步：粘贴你的 Spec
在标记为「OpenAPI Specification (JSON or YAML)」的大文本区域中粘贴 spec 内容。对于 YAML，在顶部包含版本声明（openapi: "3.0.0" 或 swagger: "2.0"）。
如果想先看看工具的效果，点击文本区域右上角的「Load Example」按钮。
第 2 步：点击 Validate Spec
点击文本区域下方的「Validate Spec」按钮。解析器运行时按钮显示「Validating...」。
第 3 步：查看验证结果
结果面板以两个标题之一出现：
- 「✓ Valid OpenAPI Specification」（绿色）— spec 通过了结构验证。
- 「✗ Validation Failed」（红色）— spec 有需要修复的结构错误。
第 4 步：阅读摘要磁贴（有效 Spec）
通过验证的 spec 会显示四个摘要磁贴：
- Title —
info.title的值 - Version —
info.version的值 - Paths — 路径条目的总数
- Operations — HTTP 方法+路径组合的总数
第 5 步：处理警告
即使在有效 spec 上也会显示三种警告类型：
- 缺少
info.description— spec 没有整体 API 描述。 - 没有 description 或 summary 的操作 — 以计数形式报告。
- 没有
operationId的操作 — SDK 生成器使用operationId来命名生成的方法。
实际应用示例
示例 1：找到缺失的必填字段
✗ Validation Failed
Could not resolve reference: #/definitions/UserProfile示例 2：带有质量警告的有效 Spec
✓ Valid OpenAPI Specification 5 warnings
info.description: Missing API description — helps users understand the API purpose
paths.*: 12 operation(s) missing operationId — required for SDK generation示例 3：快速检查大型 Spec
粘贴 500 路径的内部 API spec 后，摘要磁贴显示「Paths: 147」和「Operations: 312」。
提示和最佳实践
每次结构更改后进行验证。 添加新路径、更改 $ref 或修改 schema 都可能引入错误。验证不到两秒。
将 operationId 警告视为 SDK 工作流的阻碍。 未设置意味着生成的方法名将从路径派生。
使用示例作为模板。 内置示例是一个完整、有效、最小的 OpenAPI 3.0 spec。
区分结构有效性和语义正确性。 验证器确认 spec 遵循 OpenAPI schema，但不确认它准确描述了您的实际 API。
从上到下修复错误。 单个缺失的 schema 定义可能在整个 spec 中导致级联 $ref 错误。
常见问题和故障排除
「Parse error: ...」 — 输入既不是有效 JSON 也不是有效 YAML。常见原因：JSON 中的尾逗号、不一致的 YAML 缩进或 YAML 缩进中使用了制表符。
Swagger UI 接受的 spec 在这里验证失败。 Swagger UI 对错误容忍。此验证器应用严格的 schema 验证。
添加描述后仍显示警告。 确认在 info 内部添加了 description，而不仅仅是在各个路径上。
首次使用时工具似乎很慢。 库在首次验证点击时动态加载。
隐私和安全
OpenAPI 验证器完全在浏览器中处理你的 spec。@readme/openapi-parser 库在本地运行——没有 spec 内容发送到任何外部服务或服务器。页面和解析器库加载后，工具完全离线运行。
常见问题解答
OpenAPI 验证器是免费的吗？ 是的。没有费用、帐户或使用限制。
支持哪些 OpenAPI 版本？ Swagger 2.0、OpenAPI 3.0.x 和 OpenAPI 3.1.x。
可以粘贴 YAML 吗？ 两种格式都可以。
工具会验证我的实际 API 端点吗？ 不会。验证器仅检查 spec 文件是否结构正确。
为什么我的 spec 在这里失败但在 Swagger UI 中有效？ Swagger UI 对错误有容忍度。此验证器应用严格的 schema 验证。
「operationId required for SDK generation」是什么意思？ SDK 生成器根据 operationId 值命名生成的方法。没有它们，名称将从 HTTP 方法和路径构建。
警告中有误报吗？ 三项警告检查是保守的。info.description 检查仅在字段缺失或为空时触发。
可以验证 spec 文件而不是粘贴吗？ 工具仅接受粘贴的文本——没有文件上传按钮。
历史面板会保存我的 spec 内容吗？ 会。本地保存在浏览器的 IndexedDB 中。
粘贴空 spec 会怎样？ 文本区域为空时 Validate 按钮会被禁用。
相关工具
- 即将推出: API Mock 生成器 — 从验证过的 spec 生成 mock 响应数据用于前端开发。
- 即将推出: API 设计套件 — 在导出为 OpenAPI 格式之前设计和迭代 API 结构。
- JSON 格式化器 — 在粘贴到验证器之前格式化和验证 spec 的 JSON 结构。
立即试用 OpenAPI 验证器：OpenAPI 验证器