OpenAPI / Swagger规范验证器
指导
OpenAPI / Swagger规范验证器
即时验证您的 OpenAPI 3.0、3.1 或 Swagger 2.0 规范。粘贴 YAML 或 JSON，获取结构化的错误和警告列表，其中包含 JSON Pointer 路径，并美化您的规范以实现清晰的文档。
如何使用
将您的 OpenAPI 或 Swagger 规范粘贴到输入字段中。验证器会自动检测它是 YAML 还是 JSON，以及您正在使用的规范版本。结果显示端点、架构、错误和警告的摘要。每个问题都包含一个 JSON Pointer 路径，以便您可以快速找到问题。
特征
- 多版本支持 – 验证 Swagger 2.0、OpenAPI 3.0.x 和 OpenAPI 3.1.x 规范
- 结构验证 – 检查必需字段（info、paths、version）、正确类型和架构结构
- 语义验证 – 检测重复的 operationIds、无效的 HTTP 方法、损坏的 $ref 引用和路径参数不一致
- 错误路径 – 每个问题都包含一个 JSON Pointer 路径，用于精确查找
- 美化打印 – 以清晰的 JSON 或 YAML 格式重新格式化您的规范，并带有正确的缩进
- 规范摘要 – 即时概览：版本、总端点、架构、错误和警告
- 100% 客户端 – 您的 API 规范永远不会离开您的浏览器
常问问题
-
Swagger 2.0 和 OpenAPI 3.0 之间有什么区别？
Swagger 2.0 是 SmartBear 开发的原始 API 规范格式。当该规范于 2015 年捐赠给 OpenAPI Initiative 时，它被重命名为 OpenAPI。3.0 版本引入了重大改进，包括对回调、链接、多个服务器以及更清晰的组件结构的支持更好。这两种格式不直接兼容。
-
为什么 OpenAPI 规范中的 operationIds 需要唯一？
operationIds 是每个 API 操作的唯一标识符。代码生成器使用它们在客户端 SDK 中创建方法名称，文档工具使用它们进行锚点链接，测试框架使用它们来引用特定的端点。重复的 operationIds 会在所有这些下游工具中引起冲突。
-
什么是 JSON Pointer，如何读取验证错误路径？
JSON Pointer (RFC 6901) 是一种用于识别 JSON 文档中特定值的字符串语法。例如，/paths/~1users/get/parameters/0 指向 GET /users 操作的第一个参数。~1 转义路径段中的正斜杠。读取这些指针可以确切地告诉您验证错误在您的规范中的哪个位置。
-
我应该用 YAML 还是 JSON 编写 OpenAPI 规范？
这两种格式都得到完全支持并且功能上等效。YAML 通常更适合手动编写的规范，因为它更具可读性并支持注释。JSON 更适合机器生成的规范和程序化操作。大多数工具都接受这两种格式，因此请选择您的团队认为更容易维护的格式。
