Softonic

OpenAPI YAML 验证器

步 1 / 2
下一步

粘贴你的 openapi.yaml，验证器会检查每个规范都必需的部分：version 字段、包含 title 和 version 的 info 对象，以及 paths 对象。它还会对没有以斜杠开头的路径键，以及无法识别的操作键发出警告。

如何验证 OpenAPI YAML 文件

  1. 1

    复制 YAML

    复制 `openapi.yaml` 或 `swagger.yaml` 的完整内容，并保持缩进完全不变。

  2. 2

    粘贴到输入框

    粘贴到 OpenAPI / Swagger 文档输入框中。在 YAML 中，缩进就是结构本身，请不要重新输入或重新排版。

  3. 3

    运行验证

    进入结果步骤，阅读错误和警告。

  4. 4

    修正并重新检查

    在你的文件中修复每一项报告内容，粘贴新版本后再次运行。

为什么缩进会影响结果

在 YAML 中，键的嵌套决定了字段属于哪个对象。如果 version 与 info 处于同一缩进层级，而不是缩进在它下面一级，文档仍然是可读的 YAML，但 info.version 就会缺失，检查会报告它。paths 也是同样的道理：如果一个路径键被误缩进到了 info 之下，顶层的 paths 对象就不存在了。

请使用空格而不是制表符，并保持一致的缩进步长，例如每级两个空格。

实例

openapi: 3.0.3
info:
  title: Pets API
paths:
  /pets:
    get:
      summary: List pets

version 字段、info.title 和 paths 都已存在，/pets 以斜杠开头，而 get 是已知方法。只缺少一项：info.version。报告会列出：

检查结果 类型
info.version is required. 错误

在 info 下添加两个空格缩进的 version: 1.0.0，文档就会被判定为结构有效。

保持文档简单，以获得可靠的读取结果

检查最擅长读取普通的 YAML 映射：以一致的缩进嵌套的简单 key: value 行。如果包含锚点或多行块等高级 YAML 功能的文档被报告为无法读取，或显示字段缺失，请尝试同一规范的 JSON 副本，以确认问题出在内容上还是 YAML 语法上。

检查通过只能确认骨架正确，并不会解析 $ref 引用，也不会检查架构。

YAML 规范的实用工作流

小步修改，并随时重新检查。在添加新路径或移动某个代码块之后，重新粘贴文件，这样在改动还新鲜时就能发现错误的缩进。如果你把大规范拆分到多个文件中，请粘贴合并后的版本，因为本检查只读取你提供的文本，不会加载其他文件。请从编辑器复制，而不是从渲染后的页面复制，因为网页可能会把空格和引号替换为外观相似的字符，从而改变 YAML 的解析方式。

最后，请记住报告只列出检查能够看到的内容。YAML 文件检查通过，说明顶层骨架正确，但并不代表其中每个操作、架构或引用都正确。

常见问题

使用空格。YAML 不接受制表符作为缩进，制表符可能导致文档无法读取，或使字段被移动到错误的层级。

通常是字段的缩进层级不对，导致它属于另一个对象。请将它的缩进与父级键进行比较。

本检查只查找 openapi 或 swagger 字段是否存在，不检查其值，因此加引号和不加引号的版本都能通过。不过，Swagger 中把 "2.0" 加上引号仍然是个好习惯。

可以。内容会先按 JSON 读取，失败后再按 YAML 读取，因此两种格式都可以在同一个输入框中使用。

相关工具

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

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

使用指南与应用场景