Softonic

OpenAPI JSON 验证器

步 1 / 2
下一步

粘贴 openapi.json 或 swagger.json 文件的内容，几秒钟即可完成结构检查。验证器会确认 JSON 能否解析、version 字段是否存在、info 是否包含 title 和 version、paths 是否存在，然后对不规范的路径名称和未知的操作键发出警告。

如何验证 OpenAPI JSON 文件

  1. 1

    复制文件

    打开 `openapi.json`，复制整个文档，从起始大括号到结束大括号。

  2. 2

    粘贴到输入框

    粘贴到 OpenAPI / Swagger 文档输入框中。无需删除空白或重新格式化。

  3. 3

    运行检查

    进入结果步骤，运行验证。

  4. 4

    修复并重复

    针对每个错误修改文件，重新粘贴并再次运行，直到报告中不再有错误。

导致检查失败的常见 JSON 错误

JSON 比 YAML 更严格，因此手动编辑的文件大多是因为语法问题而失败，而不是 API 设计问题。常见原因包括：最后一个属性后面有多余的逗号、使用了单引号而不是双引号、写入了注释（JSON 不允许注释），或者在较长的 paths 对象后缺少结束大括号。损坏的文件通常会以 “Could not parse as JSON or YAML” 提示结束，或者因为没有读取到可用内容而出现缺少字段的错误。

如果只看到解析错误，请先找出语法错误。文档被读取为对象之后，才会运行结构检查。

实例

看看这个小文档：

{
  "openapi": "3.0.3",
  "info": { "title": "Orders API" },
  "paths": {
    "orders": { "get": { "summary": "List orders" } }
  }
}

它可以正常解析，openapi 字段和 paths 对象也都存在。但报告仍会显示：

检查结果 类型 原因
info.version is required. 错误 info 有 title，但没有 version
Path ‘orders’ should start with ‘/’. 警告 路径键没有以斜杠开头

由于存在一个错误，该文档不会被判定为有效。请在 info 中添加 "version": "1.0.0"，并将键名改为 /orders。第二次运行即可清除这两项提示。

通过检查意味着什么，不意味着什么

报告干净只表示骨架正确。它不会跟随 $ref 链接，不检查架构，也不能确认每个操作都有响应。请把它当作提交文件之前的快速关卡，更深入的规则则交给完整的 Linter。

JSON 规范的实用工作流

将规范保存在版本控制中，每次提交涉及 paths 的更改之前，都把它粘贴到这里。由于检查很快，它也适合作为合并多人修改之后的健全性检查，因为这时最容易出现重复的键或位置错误的大括号。如果你的 JSON 由构建脚本生成，请粘贴生成后的输出而不是模板，这样测试的就是读者真正会收到的内容。报告干净之后，你就可以更有把握地分享文件，或将其交给文档生成器，因为顶层结构已经可靠。

常见问题

不需要。空白和缩进不影响结果，按原样粘贴即可。

标准 JSON 不允许在对象或数组的最后一项后面加逗号，因此文档无法被读取为 JSON。删除逗号后重新检查即可。

可以。版本检查同时接受 openapi 字段或 swagger 字段，因此 Swagger 2.0 和 OpenAPI 3.x 的 JSON 文件都会经过相同的结构检查。

不会。检查结果以消息形式列出，例如缺少字段或路径名称，不显示行号。请在文件中搜索消息里提到的键。

相关工具

Webpack 配置生成器

为纯 JavaScript、React 或 Vue 项目生成 webpack 5 的 webpack.config.js：支持 TypeScript、Babel、CSS 或 Sass、图片、HtmlWebpackPlugin、开发服务器，并给出 npm install 命令。

ASCII 表参考

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

Protocol Buffers 解码器

在浏览器中解码 hex、Base64、Base64URL、文本或文件中的 Protobuf 线格式字节，准确检查字段候选解释并导出私密报告。

XML 格式化工具

以一致的缩进美化 XML 文档，并精确定位到行号，捕获格式良好性错误。

HTML 字符参考

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

文件大小转换器

在字节、KB、MB、GB、TB及IEC二进制单位（KiB、MiB、GiB、TiB）之间转换，可自由组合十进制与二进制。

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

使用指南与应用场景