跳到主要内容

OpenAPI 与 Swagger 查看器和校验器 — YAML 或 JSON

粘贴 OpenAPI 3.x 或 Swagger 2.0 规范,即可按标签浏览文档、检查结构错误,并为每个接口生成 cURL 示例。

OpenAPI 3.0 · Bookstore API 1.2.0 · 4 个操作 · 1 个错误,0 个警告

校验

  • 错误 路径中使用了 {itemId},但没有声明名为“itemId”的 in: path 参数。
    位置:paths./orders/{orderId}/items/{itemId}.get
检查内容

查看器会检查以下取自 OpenAPI 3.0 / 3.1 和 Swagger 2.0 规范的结构规则。这不是对文档的完整 JSON Schema 校验:不会检查单个 schema 关键字(minimum、pattern、format 等)。

  • 文档是有效的 YAML 或 JSON。
  • 声明了 openapi: 3.0.x 或 3.1.x,或 swagger: "2.0"。
  • 存在 info,并含 title 和 version(字符串)。
  • 存在 paths(在 3.1 中,若有 components 或 webhooks 则可选)。
  • 每个路径都以 / 开头。
  • 路径项只包含 HTTP 方法、parameters、$ref、summary、description、servers(或 x- 扩展)。
  • 每个操作都有 responses(在 2.0 和 3.0 中为错误,在 3.1 中为警告)。
  • responses 不为空。
  • 响应的键是状态码(200)、default,或(3.x)2XX 这样的范围。
  • 每个响应都有 description。
  • operationId 的值唯一。
  • 路径中的每个 {name} 都有对应的 in: path 参数。
  • 每个 in: path 参数都出现在路径中。
  • 路径参数设置了 required: true。
  • 每个参数都有 name 和 in。
  • in 为 query、header、path 或 cookie(2.0:query、header、path、formData 或 body)。
  • 没有 name 和 in 都相同的重复参数。
  • 参数有 schema 或 content(2.0:body 参数有 schema,其他参数有 type)。
  • 2.0:最多一个 body 参数,且不能与 formData 同时使用。
  • 3.x:requestBody 含有 content。
  • 每个本地 $ref(#/…)都指向存在的内容。
  • 指向其他文件或 URL 的引用会被报告(不会被获取)。
  • 安全要求引用的是已定义的安全方案。

文档: Bookstore API 1.2.0

A small example API. Edit it or paste your own spec.

基础 URL:https://api.example-bookstore.com/v1

Books

Browse and manage the catalogue

GET/booksList books
POST/booksAdd a book
GET/books/{bookId}Get one book

Orders

Place and track orders

GET/orders/{orderId}/items/{itemId}Get an order line

数据模型

NewBook
Book
Author
OrderItem

完全在浏览器中运行。你的 API 规范绝不会被上传,外部 $ref 也不会被获取。 浏览全部免费工具.

发现问题,或者觉得哪里可以更好?每条消息我们都会阅读,并尽快修复。

这款 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 会被列出,但不会被获取。

使用方法

  1. 粘贴你的 openapi.yaml、openapi.json 或 swagger.json,或打开文件。初始会载入一个示例 API。
  2. 查看状态行和“校验”列表。每个问题都会写明规则名称和所在位置(例如 paths./pets/{id}.get)。
  3. 浏览文档:操作按标签分组;点击某个操作即可查看参数、请求体、响应和数据模型。
  4. 按路径、摘要或 operationId 筛选,在大型规范中快速找到接口。
  5. 复制某个操作的 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")。

• 安全要求引用了未定义的方案,导致生成的客户端无法认证。