什么是 OpenAPI / Swagger 格式化器？

它是一款工具，可解析 OpenAPI 3.x 或 Swagger 2.0 API 规范，并将其重新输出为整洁、缩进一致的 JSON 或 YAML，同时报告版本以及路径和操作的数量，让你能够快速审查和统一规范。

它同时支持 JSON 和 YAML 规范吗？

支持。由于 JSON 本身就是有效的 YAML，你可以粘贴任一格式。使用 JSON / YAML 切换来选择格式化输出的方式，这也让你能将规范从一种格式转换为另一种。

它会针对 OpenAPI 模式完整校验我的规范吗？

它会校验文档能否解析为格式良好的 JSON 或 YAML，并检测版本、标题、路径和操作。它不会对每个字段运行完整的 JSON Schema 校验，因此不会标记某个操作深处缺失的必需属性。

它识别哪些版本？

它通过 openapi 字段标注 OpenAPI 3.x，通过 swagger 字段标注 Swagger 2.0。任何不含这些字段的文档都会被格式化，但标记为未知版本。

我的 API 规范会被上传到任何地方吗？

不会。解析、校验和格式化完全在你的浏览器中运行。你粘贴的规范绝不会离开你的设备，也不会上传任何内容到 ArrayKit，因此内部或未发布的 API 契约保持私密。

我可以下载格式化后的结果吗？

可以。格式化后的规范可以复制或下载为 openapi.json 或 openapi.yaml，取决于你选择的输出格式。

OpenAPI 格式化器

Name: OpenAPI / Swagger 格式化工具
Author: ArrayKit

OpenAPI 格式化器，可美化并校验 JSON 或 YAML 格式的 Swagger 和 OpenAPI 规范，并统计路径和操作数。

这是一款本地工具：它完全在你的浏览器中运行。你粘贴的 OpenAPI 或 Swagger 规范绝不会离开你的设备——不会上传任何内容到 ArrayKit 或任何服务器。

由 Udit Agarwal 开发和维护

在 YAML 和 JSON 之间转换

关于 OpenAPI / Swagger 格式化工具

ArrayKit OpenAPI 格式化器可在你的浏览器中美化并校验 JSON 或 YAML 格式的 OpenAPI 和 Swagger 规范。粘贴一份规范，它便会解析该文档，报告检测到的版本（OpenAPI 3.x 或 Swagger 2.0）、API 标题，并统计它定义了多少路径和操作，然后重新输出整洁、缩进一致的 JSON 或 YAML。它专为需要快速整理手动编辑的契约、在 JSON 与 YAML 之间转换，或在提交规范或将其提供给 Swagger UI、代码生成器或网关之前进行检查的后端和 API 开发者、技术文档作者以及平台团队而设计。由于请求构建和解析都在本地进行，你可以格式化内部或未发布的 API 定义而无需将它们发送到服务器。用它来捕捉格式错误的 YAML、确认操作数量，并在整个仓库中统一格式。

功能特性

同时接受 JSON 和 YAML 输入——JSON 本身就是有效的 YAML，因此两者都能解析
检测并标注规范版本：OpenAPI 3.x 或 Swagger 2.0
报告 API 标题以及路径和操作的实时计数
统计八种 HTTP 操作（get、put、post、delete、options、head、patch、trace）
通过 JSON / YAML 切换在美化打印的 JSON 和 2 空格 YAML 之间切换输出
当文档格式错误时，呈现解析错误及其底层消息
当不存在 openapi 或 swagger 字段时发出警告，让未知规范凸显出来
将格式化后的结果下载为 openapi.json 或 openapi.yaml

如何使用 OpenAPI / Swagger 格式化工具

将你的 OpenAPI 或 Swagger 规范（JSON 或 YAML）粘贴到输入面板中
使用工具栏中的 JSON / YAML 切换选择输出格式
阅读摘要横幅了解版本、标题、路径数和操作数
复制格式化后的规范或将其下载为 openapi.json 或 openapi.yaml

示例

输入

openapi: 3.0.3
info: { title: Example API, version: 1.0.0 }
paths:
  /users:
    get: { summary: List users, responses: { '200': { description: OK } } }
    post: { summary: Create user, responses: { '201': { description: Created } } }

输出

openapi: 3.0.3
info:
  title: Example API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users
      responses:
        '200':
          description: OK
    post:
      summary: Create user
      responses:
        '201':
          description: Created

一份最简的 OpenAPI 3.0 规范——格式化器报告 'OpenAPI 3.0.3 · Example API · 1 path · 2 operations'。

常见错误与故障排除

摘要显示 'Unknown — no openapi/swagger field'（未知——没有 openapi/swagger 字段）。 — 添加一个顶层的 openapi: 3.x.x（或 swagger: '2.0'）字段；没有它就无法检测版本，尽管文档仍能格式化。
出现 YAML 解析错误，通常关于错误的缩进或制表符。 — YAML 对缩进敏感且禁止制表符——请将制表符替换为空格并使键对齐一致，然后重新粘贴。
操作数看起来低于预期。 — 只统计八种标准 HTTP 方法；x-amazon-apigateway-integration 等供应商扩展以及 parameters/servers 条目不算作操作。
粘贴后出现 'The document is empty or not an object'（文档为空或不是对象）。 — 输入被解析为标量或 null——请确保你粘贴了完整的规范对象，而非单个字符串或部分片段。

常见问题

什么是 OpenAPI / Swagger 格式化器？: 它是一款工具，可解析 OpenAPI 3.x 或 Swagger 2.0 API 规范，并将其重新输出为整洁、缩进一致的 JSON 或 YAML，同时报告版本以及路径和操作的数量，让你能够快速审查和统一规范。
它同时支持 JSON 和 YAML 规范吗？: 支持。由于 JSON 本身就是有效的 YAML，你可以粘贴任一格式。使用 JSON / YAML 切换来选择格式化输出的方式，这也让你能将规范从一种格式转换为另一种。
它会针对 OpenAPI 模式完整校验我的规范吗？: 它会校验文档能否解析为格式良好的 JSON 或 YAML，并检测版本、标题、路径和操作。它不会对每个字段运行完整的 JSON Schema 校验，因此不会标记某个操作深处缺失的必需属性。
它识别哪些版本？: 它通过 openapi 字段标注 OpenAPI 3.x，通过 swagger 字段标注 Swagger 2.0。任何不含这些字段的文档都会被格式化，但标记为未知版本。
我的 API 规范会被上传到任何地方吗？: 不会。解析、校验和格式化完全在你的浏览器中运行。你粘贴的规范绝不会离开你的设备，也不会上传任何内容到 ArrayKit，因此内部或未发布的 API 契约保持私密。
我可以下载格式化后的结果吗？: 可以。格式化后的规范可以复制或下载为 openapi.json 或 openapi.yaml，取决于你选择的输出格式。