Softonic

OpenAPI 3.1 验证器

步 1 / 2
下一步

将 OpenAPI 3.1 文档以 JSON 或 YAML 格式粘贴到这里，即可检查其顶层结构。工具会查找 openapi 字段、包含 title 和 version 的 info 对象，以及 paths 对象。这是一项结构检查，不会验证 3.1 的架构关键字。一些符合 3.1 习惯的写法可能会产生警告或错误，请提前了解。

如何检查 3.1 文档

  1. 1

    粘贴你的 3.1 规范

    将包含 `openapi: 3.1.0`（或其他 3.1.x 值）的文档以 JSON 或 YAML 格式粘贴到输入框中。

  2. 2

    运行检查

    进入结果步骤，查看错误和警告。

  3. 3

    阅读 3.1 说明

    判断被标记的内容是真正的错误，还是下文所述的 3.1 写法。

  4. 4

    使用完整的 Linter 继续检查

    结构无误后，使用完整的验证器检查 JSON Schema 2020-12 的规则。

本工具如何处理 3.1 文件

3.1 版本使架构与 JSON Schema 2020-12 保持一致。本验证器完全不读取架构内部内容，它只检查顶层和路径条目。因此，类型数组或 const 等 3.1 架构特性在这里既不会通过，也不会失败。openapi 字段的值本身也不检查，只要存在 openapi 字段，就视为有效。

需要注意的两种 3.1 写法

3.1 文件中的写法 工具的报告
有 webhooks 对象但没有 paths 对象 错误：Missing ‘paths’ object.
路径下的 trace 操作 警告：Unknown method ‘trace’ on the path
路径项中以 $ref 作为键 警告：Unknown method ‘$ref’ on the path

OpenAPI 3.1 允许只描述 webhooks 而省略 paths。本工具要求必须有 paths，因此即使规范允许，这样的文件也会被报告为错误。添加一个空的 paths: {} 对象即可通过检查。

本工具使用的方法列表包括 get、post、put、patch、delete、head、options，以及 parameters、summary、description 和 servers。trace 方法存在于规范中，但不在该列表内，因此如果是有意为之，它会触发一条可以忽略的警告。警告不会使文档失效。

实例

openapi: 3.1.0
info:
  title: Events API
  version: 2.0.0
webhooks:
  newEvent:
    post:
      summary: Event delivered

结果：一个错误，即 “Missing ‘paths’ object.”。添加 paths: {} 后，结构检查即可通过。

何时使用本工具，何时需要更进一步

在提交合并请求或与合作方分享 3.1 文件之前，使用本页面确认文件结构正确。检查速度快，提示信息也很直白。结构正确之后，3.1 的架构规则仍需使用完整的 Linter 来检查，因为大多数真正的错误都藏在那里，例如无效的类型声明、断开的引用以及缺失的响应定义。请把这两个步骤视为互补关系，而不是二选一。

如果某条警告是有意为之（例如 trace），请在合并请求中注明，以免审阅者产生疑问。警告不会改变有效结果，因此保留它们是安全的。分享文件前需要解决的是错误。

常见问题

不会。它不检查架构对象的内部，因此不检查 JSON Schema 2020-12 的关键字。它只检查顶层结构和路径条目。

检查要求必须有 paths 对象。只包含 webhooks 的 3.1 文件没有该对象，因此会报告缺少 paths 的错误。添加空的 paths: {} 即可通过。

不会。工具只检查 openapi 或 swagger 字段是否存在，不检查其值。

不一定。trace 是规范中有效的操作，只是工具没有把它包含在已知方法列表中。

相关工具

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）之间转换，可自由组合十进制与二进制。

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

使用指南与应用场景