OpenAPI / Swagger 校验器
在线校验 Swagger 2.0 与 OpenAPI 3.0/3.1/3.2(YAML/JSON):官方 Schema、跨文件 $ref、路径参数、安全方案、示例与 schema 是否一致,错误带行号。文件不上传。
- 在浏览器中处理
- 工具不会把输入上传到 ZeroTool 服务器
- 免费 · 无需注册
用微信扫描以下二维码即可分享
示例、说明与常见问题 带实际输出的示例、与同类工具的差别,以及常见问题。
把 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 写法。