这款 OpenAPI 查看器和校验器可以读取 YAML 或 JSON 格式的 OpenAPI 3.0、3.1 或 Swagger 2.0 文档,并把它显示为可浏览的 API 文档:所有接口按标签分组,列出参数、请求体、响应和数据模型,还附带可直接运行的 cURL 命令。粘贴规范或打开文件即可;不会上传任何内容,内部和未发布的 API 也能保持私密。
校验器会执行 23 项取自规范本身的结构检查,每一项都列在页面上:info 和 paths 是否存在,响应是否有 description 和有效的状态码,路径中的每个 {parameter} 是否都声明为必填的路径参数,operationId 是否唯一,$ref 能否解析,安全要求是否引用了已定义的方案。这些正是会导致代码生成器和文档工具出错的问题。它并不是按规范官方 JSON Schema 进行的完整校验,因此在这里通过的规范仍可能存在问题,比如拼错的 schema 关键字。指向其他文件的外部 $ref 会被列出,但不会被获取。
使用方法
- 粘贴你的 openapi.yaml、openapi.json 或 swagger.json,或打开文件。初始会载入一个示例 API。
- 查看状态行和“校验”列表。每个问题都会写明规则名称和所在位置(例如 paths./pets/{id}.get)。
- 浏览文档:操作按标签分组;点击某个操作即可查看参数、请求体、响应和数据模型。
- 按路径、摘要或 operationId 筛选,在大型规范中快速找到接口。
- 复制某个操作的 cURL 示例,并把 <TOKEN> 或 <API_KEY> 占位符替换为你的凭据。
常见问题
如何查看 Swagger 或 OpenAPI 文件?
把 YAML 或 JSON 粘贴到输入框中,或打开文件。查看器会识别版本(swagger: "2.0" 或 openapi: 3.0.x / 3.1.x),按标签分组列出接口,并可展开每个接口查看参数、请求体、响应和已解析的数据模型。页面加载后离线也能使用。
OpenAPI 校验器会检查什么?
规范中的结构规则:受支持的版本字段;info 含 title 和 version;路径以 / 开头;操作的 responses 不为空,且每个响应都有 description 和有效状态码;路径模板参数已声明且为必填;参数含 name、有效的 in 和 schema;没有重复的参数或 operationId;请求体含 content;$ref 能解析;安全要求引用已定义的方案。完整列表见页面上的“检查内容”。它不会按官方 JSON Schema 校验每一个 schema 关键字。
为什么未声明的路径参数会被判为错误?
规范要求路径模板中的每个 {name} 都要在路径或操作层级有一个对应的参数,并设置 in: path 和 required: true。一些只按 JSON Schema 校验文档的工具会放过缺失的参数,但代码生成器随后会生成一个缺少该参数的函数,文档工具也会显示一个无法被正确调用的接口。
能读取 OpenAPI 3.1 和 Swagger 2.0 吗?
可以。Swagger 2.0 的 body 和 formData 参数会显示为请求体,produces 和 consumes 显示为媒体类型,因此三个版本的阅读方式一致。OpenAPI 3.1 的差异也会被考虑:存在 components 或 webhooks 时 paths 可选,responses 可选(这里显示为警告),type: [string, "null"] 显示为 nullable。
会加载外部 $ref 文件吗?
不会。指向其他文件或 URL 的 $ref(例如 ./schemas/user.yaml)会作为警告列出并显示为未解析,因为页面无法读取你没有打开的文件,也不会自行获取 URL。请先把多文件规范打包成一个文档,例如使用 redocly bundle 或 swagger-cli bundle。
我的 API 规范会被上传吗?
不会。解析、校验和渲染都在你的浏览器中进行,规范绝不会被发送到任何地方。
OpenAPI 3.x 与 Swagger 2.0:有哪些变化
• 版本字段:swagger: "2.0" 变成了 openapi: 3.0.x,后来又变成 3.1.x。
• 服务器:2.0 使用 host、basePath 和 schemes;3.x 使用带变量的 servers 列表。
• 请求体:2.0 使用 in: body(或 formData)的参数;3.x 使用 requestBody,按媒体类型提供 content。
• 可复用部分:2.0 的 definitions、parameters 和 responses 位于顶层;3.x 把它们放在 components 下,与 securitySchemes、requestBodies 和 examples 并列。
• 3.1 的 schema 与 JSON Schema 2020-12 对齐:type 可以是列表(用 ["string", "null"] 代替 nullable: true),examples 是数组,并新增了 webhooks。
最常导致 API 工具出错的问题
• 路径参数未声明,或声明时没有 required: true。
• $ref 有拼写错误(把 schemas 写成 #/components/schema/User),导致部分文档为空。
• operationId 重复,导致代码生成器失败或覆盖方法。
• 响应缺少 description(它是必填项,哪怕只写 "OK")。
• 安全要求引用了未定义的方案,导致生成的客户端无法认证。
