# OpenAPI / Swagger 校验器

对 OpenAPI 3.0/3.1 与 Swagger 2.0 文档进行结构校验：必填字段、路径/操作完整性、响应码、$ref 引用解析、operationId 唯一性与组件完整性

> 标准页面: https://elysiatools.com/zh/tools/openapi-validator

- **分类:** Validation

- **关键词:** openapi, swagger, 校验, api, 规范, rest, 文档

## 概述

OpenAPI / Swagger 校验器是一款专业的 API 规范验证工具，支持对 OpenAPI 3.0/3.1 与 Swagger 2.0 格式的文档进行深度结构校验。它能快速检测必填字段缺失、路径与操作完整性、响应状态码规范、$ref 引用解析、operationId 唯一性以及组件完整性，帮助开发者确保 API 定义的准确性与合规性。

## 输入项

- **OpenAPI / Swagger 文档** (textarea): openapi: 3.0.3 info: title: Example API version: 1.0.0 paths: /users: get: summary: List users responses: '200': description: OK

## 适用场景

- 在将 API 设计文档导入网关或生成客户端 SDK 前，需要确保其符合 OpenAPI 规范。
- 团队协作开发中，合并 API 变更分支时，需要校验 Swagger JSON/YAML 的语法与结构。
- 调试复杂的 $ref 嵌套引用或排查 API 渲染工具（如 Swagger UI）报错时。

## 工作原理

- 将 OpenAPI 3.0/3.1 或 Swagger 2.0 格式的 JSON 或 YAML 文本粘贴至输入框中。
- 校验器解析文档结构，自动检索必填字段、解析 $ref 引用，并检查 operationId 是否唯一。
- 实时输出校验结果，高亮显示不合规的路径、缺失的组件或错误的响应码配置。

## 使用案例

- API 设计合规性检查：在发布 API 之前，验证必填字段（如 info.title、paths）和响应码是否定义完整。
- 排查 Swagger UI 渲染失败：当 Swagger UI 无法正常加载文档时，通过校验器快速定位损坏的 $ref 引用或重复的 operationId。
- CI/CD 流程前的预校验：在将 API 规范提交到代码仓库前，手动粘贴进行快速结构验证，防止破坏自动化构建流。

## 常见问题

### 这个校验器支持哪些版本的 API 规范？

支持 OpenAPI 3.0、OpenAPI 3.1 以及较旧的 Swagger 2.0 规范。

### 校验器可以解析外部的 $ref 引用吗？

校验器主要解析文档内部的 $ref 组件引用，确保引用的组件在 components 或 definitions 中真实存在。

### 为什么我的 YAML 格式文档粘贴后报错？

请确保 YAML 缩进正确。校验器会先解析 YAML 结构，若格式有误会提示具体的语法错误位置。

### 校验器会检查 operationId 的唯一性吗？

会的，校验器会扫描所有路径下的操作，确保每个 operationId 在整个文档中是唯一的，以避免 SDK 生成冲突。

### 校验失败时会提供具体的错误位置吗？

是的，校验结果会明确指出出错的路径、字段名称以及具体的规范冲突原因。

## 相关工具

- [全球邮政编码校验器](https://elysiatools.com/zh/tools/global-postal-code-validator): 验证多国邮政编码格式，包括美国ZIP、英国邮编、加拿大等
- [国际银行账户校验器](https://elysiatools.com/zh/tools/iban-swift-validator): 验证国际银行账户号码（IBAN）和银行识别码（SWIFT/BIC）的格式与校验位
- [Mod-11 校验码计算器](https://elysiatools.com/zh/tools/mod11-checksum): 使用模 11（ISO 7064）校验位算法校验或生成数字，支持 ISBN-10（10..2）、挪威身份证（3,7,6,1,8,9,4,5,2）与通用 2-7 权重方案。
- [美国邮政编码验证器](https://elysiatools.com/zh/tools/us-zip-code-validator): 验证美国邮政编码，包括标准5位和ZIP+4格式
- [货币代码验证器](https://elysiatools.com/zh/tools/currency-validator): 验证 ISO 4217 货币代码
- [邮箱验证器](https://elysiatools.com/zh/tools/email-validator): 验证邮箱地址并检查可送达性
- [.env 文件验证器](https://elysiatools.com/zh/tools/env-file-validator): 验证 .env 文件的语法错误和常见问题
- [多国家手机号码验证工具](https://elysiatools.com/zh/tools/global-phone-validator): 验证多个国家的手机号码，包括中国、美国等，提供详细格式化和运营商信息

## 示例

- [OpenAPI/Swagger 示例](https://elysiatools.com/zh/samples/openapi): OpenAPI/Swagger 规范示例，用于 REST API 文档和契约定义
- [OpenAPI/Swagger 示例](https://elysiatools.com/zh/samples/openapi-swagger): 使用 OpenAPI 3.0 和 Swagger 规范的 RESTful 服务综合 API 文档示例
- [Android Java 图像处理示例](https://elysiatools.com/zh/samples/android-image-processing-java): Android Java 图像处理示例，包括图像读取保存、缩放和格式转换
- [Android Kotlin 图像处理示例](https://elysiatools.com/zh/samples/android-image-processing-kotlin): Android Kotlin 图像处理示例，包括图像读取保存、缩放和格式转换

## 相关内容

- [API 版本升级与破坏性变更审查](https://elysiatools.com/zh/hubs/api-versioning-breaking-change-review): 对比 API 版本、规划迁移并在发布前验收兼容性。工具不替代真实发布和运行监控。