Softonic

OpenAPI 规范在线验证器

步 1 / 2
下一步

将 OpenAPI 或 Swagger 规范粘贴到上方，即可获得错误和警告列表。本页面解释每条消息的含义以及如何修复，帮助你从红色报告快速得到干净的报告。错误会使文档无效，警告则不会。

如何检查规范并根据报告行动

  1. 1

    粘贴规范

    将文档以 JSON 或 YAML 格式粘贴到输入框中。

  2. 2

    打开结果

    进入结果步骤，查看“有效”提示或错误列表。

  3. 3

    对照每条消息

    在下方的表格中找到对应消息，并在源文件中应用修复。

  4. 4

    重新粘贴

    重复运行，直到不再有错误，然后决定哪些警告值得修复。

读懂错误消息

消息 含义 修复方法
Could not parse as JSON or YAML. 文本既无法按 JSON 读取，也无法按 YAML 读取 修正语法：多余的逗号、缩进错误、未闭合的大括号
Missing ‘openapi’ or ‘swagger’ version field. 顶层没有版本键 添加 openapi: 3.0.3 或 swagger: "2.0"
Missing ‘info’ object. 没有 info 部分 添加包含 title 和 version 的 info
info.title is required. info 中没有 title 在 info 下添加 title
info.version is required. info 中没有 version 在 info 下添加 version（你的 API 版本）
Missing ‘paths’ object. 没有 paths 部分 添加 paths，即使一开始为空也可以

错误决定文档是否被判定为有效。请先修复所有错误。

读懂警告

消息 含义 修复方法
Path ‘x’ should start with ‘/’. paths 下的某个键没有以斜杠开头 将其重命名为 /x
Unknown method ‘x’ on /path. 路径下的某个键不在已知列表中 检查是否拼写错误；如果是有意的扩展或 trace，可以忽略

已知列表包括 get、post、put、patch、delete、head、options、parameters、summary、description 和 servers。以 x- 开头的厂商扩展不在此列表中，因此也会显示为警告。

在线检查无法告诉你的内容

报告只涵盖结构。它不会跟随 $ref 引用，不检查架构定义，也不会标记缺少的 operationId 值。通过检查只能说明文件的结构符合 OpenAPI 文档的格式。在发布文档或生成客户端代码之前，请使用完整的 Linter。

处理长报告的技巧

从顶部开始：解析错误意味着其他结果都不可靠，因此要先修复。接着处理顶层缺失的字段，因为它们很容易补上。之后才查看路径警告。每轮修改之后，请粘贴完整文件而不是片段，因为检查需要完整文档才能找到 info 和 paths。没有错误、只剩少数有意保留的警告的报告，是完全正常、可以接受的最终状态。

常见问题

错误表示文档被判定为无效。警告指出值得留意的地方，例如路径没有以斜杠开头，但不会改变有效结果。

不一定。这只说明顶层结构是完整的。架构、引用和响应都没有经过检查。

路径下的键会与固定的 HTTP 方法列表以及部分路径项字段进行比较。x- 键不在其中，因此会被标记为警告。你可以保留它。

不是。错误按照检查的顺序排列：先是版本字段，然后是 info，最后是 paths。报告中没有行号。

相关工具

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

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

使用指南与应用场景