OpenAPI / Swagger 校验器

在线校验 Swagger 2.0 与 OpenAPI 3.0/3.1/3.2(YAML/JSON):官方 Schema、跨文件 $ref、路径参数、安全方案、示例与 schema 是否一致,错误带行号。文件不上传。

  • 在浏览器中处理
  • 工具不会把输入上传到 ZeroTool 服务器
  • 免费 · 无需注册
打开或拖入 .yaml、.yml、.json 文件,总量最多 50 MiB。含 openapi 或 swagger 字段的文件会成为主文档。超过 524,288 个字符的文件以只读窗口显示,每次最多 300 行、49,152 个字符;校验仍读取全文。

粘贴 OpenAPI 或 Swagger 文档,或打开文件。

粘贴 YAML 或 JSON。所有文件合计不超过 2,097,152 个字符时,停止输入 500 毫秒后自动校验;更大的输入请点「校验」或按 Ctrl/⌘+Enter。

这里显示校验问题、文件位置和文档摘要。

附属文件名应与 $ref 中相对于主文档的路径一致,例如 schemas/pet.yaml。点「添加文件」或缺失引用旁的「添加」按钮,再粘贴内容。附属文件在本页读取用于验证,不会上传,引用的网址不会被下载。

每个文件按 $ref 里写的路径命名,路径相对于主文档(例如 schemas/pet.yaml)。文件不会上传。

示例、说明与常见问题 带实际输出的示例、与同类工具的差别,以及常见问题。

把 Swagger 或 OpenAPI 文档粘贴进来,或打开文件、拖入整个文件夹。工具按版本选用官方 JSON Schema 校验结构,跨文件解析 $ref,再补上 schema 表达不了的规则。每条问题都带行号和列号,点一下就在编辑框里选中那一行。

示例一:swag 生成的 Swagger 2.0

Gin 项目常用 swaggo/swag 从注释生成文档,它的 README 写明输出是 Swagger 2.0。下面是按 swag 输出格式写的一份 docs/swagger.yaml:路由写的是 {accountId},注释里的 @Param 却叫 id;处理函数加了 @Security ApiKeyAuth,main.go 里漏写了对应的 @securityDefinitions.apikey。

basePath: /api/v1
definitions:
model.Account:
  properties:
    id:
      example: 1
      type: integer
    name:
      example: 张三
      type: string
  type: object
info:
contact: {}
title: 账户服务 API
version: "1.0"
paths:
/accounts/{accountId}:
  get:
    parameters:
    - description: 账户 ID
      in: path
      name: id
      required: true
      type: integer
    responses:
      "200":
        description: OK
        schema:
          $ref: '#/definitions/model.Account'
    security:
    - ApiKeyAuth: []
    summary: 查询账户
swagger: "2.0"
18:5  错误  GET /accounts/{accountId}:路径参数 "accountId" 没有声明。请添加 in: path、name: accountId 的参数。
18:5  错误  GET /accounts/{accountId}:参数 "id" 写了 in: path,但路径里没有 {id}。
31:9  错误  安全方案 "ApiKeyAuth" 没有在 securityDefinitions 中声明。
33:1  提示  Swagger 2.0 文档,已按 Swagger 2.0 的 schema 校验。如需迁移到 OpenAPI 3,可先转换(例如 npx swagger2openapi swagger.yaml -o openapi.yaml),再校验转换结果。

这三处错误单靠 Swagger 2.0 的官方 schema 都查不出来:schema 只管字段的形状,不会把参数名和路径模板对照,也不会去 securityDefinitions 里找名字。

示例二:springdoc 输出的 3.0 文档里混进了 3.1 写法

Spring Boot 项目用 springdoc-openapi 时,文档默认在 /v3/api-docs(YAML 在 /v3/api-docs.yaml)。导出后手工改过的文件常见两类问题:在 openapi: 3.0.x 里写 3.1 的类型列表,示例值的类型与 schema 不一致。

openapi: 3.0.1
info:
title: 订单服务
version: v1
paths:
/orders:
  get:
    responses:
      "200":
        description: OK
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Order"
components:
schemas:
  Order:
    type: object
    properties:
      remark:
        type: [string, "null"]
      amount:
        type: number
        example: "¥19.90"
21:11  错误  OpenAPI 3.0 不允许把 type 写成列表。请写单个类型并加 nullable: true;[string, "null"] 这类写法要 OpenAPI 3.1。
24:11  警告  示例与 schema 不符:类型应为 number。

示例三:3.1 文档的服务器变量与重复路径

下面的 version 没加引号,YAML 1.2 把它读成字符串,所以不报错。真正的问题是变量默认值不在 enum 里(3.1 规定 MUST),以及两条只差参数名的路径。

openapi: 3.1.0
info:
title: 门店 API
version: 2026-10-02
servers:
- url: https://{env}.api.example.cn/v1
  variables:
    env:
      default: prod
      enum: [test, pre]
paths:
/stores/{storeId}:
  get:
    parameters:
      - {name: storeId, in: path, required: true, schema: {type: string}}
    responses:
      "200": {description: OK}
/stores/{id}:
  delete:
    parameters:
      - {name: id, in: path, required: true, schema: {type: string}}
    responses:
      "204": {description: 已删除}
9:9  错误  变量 "env" 的默认值 "prod" 不在 enum 中。
18:3  错误  路径 "/stores/{id}" 与 "/stores/{storeId}" 是同一个模板(只有参数名不同),规范不允许两者并存。

检查项与依据

检查级别依据
字段是否必填、是否允许、类型与结构错误各版本官方 JSON Schema
3.1 / 3.2 的 Schema Object(如属性上的 required: true)错误JSON Schema 2020-12 元 schema
本地 $ref 能找到目标(含其他已添加的文件)错误Reference Object
路径模板与 in: path 参数一一对应、只差参数名的路径、重复参数、重复 operationId 与标签名错误Paths Object、Parameter Object 中的 MUST
安全需求引用的方案已声明错误Security Requirement Object
服务器变量默认值在 enum 内3.1 起为错误,3.0 为警告3.0.4 写 SHOULD,3.1.1 写 MUST
布尔值 exclusiveMinimum / exclusiveMaximum 所在对象里没有 minimum / maximum(Schema Object;2.0 另含非 body 的 Parameter、Header 与 Items Object)2.0 为错误,3.0 为警告2.0 沿用 JSON Schema draft 4(§5.1.2.1 与 §5.1.3.1:必须同时出现);3.0 沿用的 Wright draft 00 删去了这条,单独写只是不起作用。官方 schema、Redocly CLI 2.57.0 与 Spectral 6.17.0 都不单独检查这一项
示例与 schema 一致、组件未被引用、变量未定义或未使用、路径里带查询串、3.1 里的 nullable警告规范的 SHOULD 与 Redocly、Spectral 也会报的常见失误

与其他工具的差异

2026-10-02 我们用同一份测试文档(含未声明的路径参数、未声明的安全方案、两条等价路径、属性上的 required: true,info.version 是不带引号的日期)对比了几款工具:

  • 命令行的 Redocly CLI 2.57.0 与 Spectral 6.17.0 都找出了四处问题,另外还有大量风格规则;swagger-parser 13.1.0 判为有效。
  • Elysia Tools 的 OpenAPI / Swagger 校验器把文档 POST 到 api.elysiatools.com,只报了一条「info.version 必须是非空字符串」,这是把日期读成时间戳造成的误报。
  • AppKits 的 Swagger/OpenAPI 校验工具在本地运行,同样误报 /info/version;把日期加上引号后显示「验证通过,0 个错误」,四处问题都没有发现。

限制

  • 不做命名、描述等风格检查,团队规则请在本工具之后跑 Redocly CLI 或 Spectral。
  • 不下载 $ref 里的网址,这类引用只列为提示、不检查;缺少的是本地文件时,请把文件添加进来。锚点引用(#name)不检查。
  • 非 JSON 媒体类型(如 application/xml)的字符串示例视为序列化后的原文,不与 schema 比对。
  • 超大文档的示例检查 4 秒后停止并给出提示;超过 2,097,152 个字符的内容需点「校验」,文件合计超过 50 MiB 不载入。
  • 打开的文件超过 512 K 字符时,校验仍针对全文,但编辑框只读显示最多 300 行、49,152 个字符:把约 10 MB 文本整份放进编辑框会让页面卡住约半秒。点行号会把显示移到那一行;「复制全文」「下载」「编辑全文(较慢)」可取得完整内容。自己把这么多文本粘贴进编辑框,页面仍会卡顿。
  • YAML 用 js-yaml 4.3.2 读取,遇到嵌套超过 100 层、合并键累计处理的映射和键超过 10,000 个、一个合并键列出超过 100 个映射的文档会停止,错误信息写明上限和行号。

相关工具:用 OpenAPI 转 TypeScript 生成器生成类型,用 JSON Schema 验证器检查请求体,用 YAML 语法验证器定位缩进错误。

FAQ

支持哪些版本?

Swagger 2.0 与 OpenAPI 3.0、3.1、3.2。工具读取 swagger 或 openapi 字段,按对应版本的官方 JSON Schema 校验:Swagger 2.0 用 OpenAPI Initiative 仓库里的 schema,3.0(2024-10-18)、3.1(2026-08-03)、3.2(2026-08-30)用 spec.openapis.org 发布的版本。

文档会上传吗?

不会。解析和全部检查都在浏览器里完成(用 Web Worker,无法启动 Worker 时退回页面线程),文档不会上传,也不会保存到浏览器存储。$ref 指向的网址不会被下载,在「其他文件」里添加的文件也只留在本页。提交文本或文件编辑、打开文件、点示例或「验证」且检查完成后,页面统计只记录工具名,并按有没有验证错误记 validate_success 或 validate_error。输入过程仍更新结果,但不记使用事件。恢复或初始渲染页面、相同验证结果、Worker 运行失败和过期回包不增加事件。统计不含文档内容。

$ref 引用了别的文件,能一起检查吗?

能。可以一次打开多个文件或整个文件夹,也可以在「其他文件」里手动添加,文件名写成 $ref 里的路径(例如 schemas/pet.yaml)。引用会跨文件解析,问题标在原文所在的文件和行。没有提供的文件和网址引用列为提示。

错误和警告有什么区别?

错误违反了规范的 MUST 或官方 schema,其他工具可能会拒收文档;警告是 SHOULD 规则和常见失误,例如示例与 schema 不符、组件没有被引用、服务器变量没有定义;提示列出没有检查的内容和需要注意的值。

info.version 写成 2024-01-15,为什么这里通过、别的工具却报错?

本工具按 YAML 1.2 core schema 读取 YAML,与 Redocly CLI、Spectral、swagger-parser 相同,所以不加引号的日期仍是字符串。按 YAML 1.1 时间戳规则读取的解析器会把它变成日期,schema 随后拒绝 info.version。给值加上引号("2024-01-15"),各种解析器都会读成字符串。

springdoc 生成的文档里 type 写成了列表,为什么报错?

OpenAPI 3.0 的 type 只能是一个字符串,可为空要写 nullable: true;type: [string, "null"] 是 OpenAPI 3.1 的写法。把 openapi 字段改成 3.1.x 也要同时检查其他 3.0 写法。