Softonic

OpenAPI 验证器

步 1 / 2
下一步

将 OpenAPI 或 Swagger 文档以 JSON 或 YAML 粘贴进来，该验证器会检查其核心结构。它确认文档能够解析，带有 openapi 或 swagger 版本字段、含标题和版本的 info 对象以及 paths 对象，然后标记不以斜杠开头的 path 和未知的 HTTP 方法。这是一次快速的结构检查，而非完整的 JSON Schema 验证器。

验证如何进行

  1. 1

    粘贴文档

    用于 OpenAPI 2（Swagger）或 OpenAPI 3 的 JSON 或 YAML。

  2. 2

    解析文档

    验证器先将文档按 JSON 解析，若失败则回退到 YAML 解析。

  3. 3

    检查必需字段

    确认存在 `openapi` 或 `swagger` 版本字段、含 `title` 和 `version` 的 `info` 对象，以及 `paths` 对象。

  4. 4

    扫描 path

    检查每个 path 是否以斜杠开头，并将每个 operation 键与已知的 HTTP 方法比对。

  5. 5

    阅读报告

    错误会导致不通过；警告会指出没有前置斜杠的 path 和未知方法。

该验证器检查什么

检查项 失败时的结果
文档能按 JSON 或 YAML 解析 错误
存在 openapi 或 swagger 字段 错误
存在 info 对象 错误
存在 info.title 错误
存在 info.version 错误
存在 paths 对象 错误
每个 path 以 / 开头 警告
operation 键是已知的 HTTP 方法 警告

通过所有错误检查的文档会被报告为结构上有效。警告不会导致不通过；它们只是指出值得修复的地方。

它不检查什么

这是结构检查，而非完整的规范验证器。它不会：

  • 对照你所用版本的官方 JSON Schema 验证每个节点；
  • 解析 $ref 引用或确认它们指向的组件存在；
  • 检查 path 参数是否被一致地声明和使用；
  • 验证 operationId 值是否存在或唯一；
  • 报告错误的行号。

若需要这种深度，请运行专门的命令行验证器，如 redocly lint、swagger-cli validate 或 spectral lint。在提交或分享规范之前，用本工具做一次快速的合理性检查。

现实中的 OpenAPI 版本

版本 说明
Swagger 2.0 仍在广泛部署；使用 swagger: "2.0"
OpenAPI 3.0.x 最常见的 3.x 系列
OpenAPI 3.1.0 与 JSON Schema 2020-12 对齐

该验证器接受 openapi 字段（3.x）或 swagger 字段（2.0），因此这些都能通过版本检查。

一个可通过的最小文档

openapi: 3.0.3
info:
  title: Example API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users

每个必需字段都存在，唯一的 path 以斜杠开头，get 是已知方法，因此它被报告为结构上有效。

常见问题

Swagger 是该规范最初的名称，于 2015 年捐赠给 Linux 基金会，并从 3.0 版起更名为“OpenAPI”。如今“Swagger”指相关工具（Swagger UI、Swagger Editor）。规范本身即为 OpenAPI。该验证器同时接受 swagger（2.0）和 openapi（3.x）版本字段。

不是。它检查核心结构：文档能否解析、是否带有版本字段、含标题和版本的 info 对象以及 paths 对象，并对没有前置斜杠的 path 和未知方法发出警告。它不会对照官方 JSON Schema 验证每个节点。做这件事请使用 redocly lint 或 spectral lint。

不会。它不会跟随 $ref 引用，也不会检查其指向的组件是否存在。对于跨文件引用，请先用 redocly bundle 或 swagger-cli bundle 之类的工具将文档打包，然后再运行完整的验证器。

不能。它只检查你粘贴的文档，而不检查你正在运行的代码。它无法判断你的 API 是否真的返回规范所描述的内容。Dredd 或 Schemathesis 这类契约测试工具才做这件事。

相关工具

ASCII 表参考

完整 ASCII 表，覆盖 0 到 127；列出每个代码的十进制、十六进制、八进制、二进制值和 HTML 数字字符引用写法，包括 NUL、LF、DEL。

HTML 字符参考

可搜索的 HTML 实体列表，含命名代码与数值代码，并支持一键复制特殊字符和符号。

键盘快捷键参考

搜索 macOS、Windows 和 Linux 上 VS Code、Chrome 以及使用 GNU Readline 的 Bash 的文档默认快捷键。

邮箱验证器

验证邮箱地址：RFC 5322 语法检查、实时 MX 记录查询，并显示本地部分、域名和长度详情。不会发送任何邮件。

编辑器配置生成器

根据你的缩进样式与大小、行尾、字符集和空格规则生成 .editorconfig 文件，让不同集成开发环境（IDE）和编辑器的格式保持一致。

证书解码器

粘贴一张 X.509 PEM 证书，并查看解码后的字段：主体、颁发者、序列号、签名算法、有效期及主体备用名称（SAN）。

此工具还提供其他语言版本