OpenAPI 格式互转指南：3 步搞定 JSON 转 YAML，告别手动排版噩梦-优快云博客

在 API 开发的江湖里，开发者们分为两派：一派是 JSON 死忠粉，另一派是 YAML 拥护者。

当你从后端同事那里通过 HTTP 拿到一份压缩成一行的 JSON 文档，却需要手动修改里面的某个参数说明时，你一定会崩溃：括号在哪里闭合？逗号漏了没？

反之，当你写好了优雅的 YAML，却发现下游的某个老旧工具只支持 JSON 解析时，同样令人头大。

今天我们就来聊聊 OpenAPI 规范中的这两位“双子星”，以及如何在它们之间实现秒级、无损的相互转换。

很多新手会困惑，既然内容都一样，为什么要有两种格式？其实它们各有千秋：

JSON (JavaScript Object Notation)
- 机器最爱：语法严格，体积小，解析速度快。几乎所有编程语言都能原生读写。
- 人类劝退：不支持注释！不支持注释！且对大括号 {} 和逗号 , 的要求极为苛刻，手写极其容易出错。
- 适用场景：API 数据传输、程序自动化处理、存储。
YAML (YAML Ain’t Markup Language)
- 人类友好：依靠缩进表示层级，结构清晰，读起来像文章。最重要的是支持注释，方便团队写备注。
- 机器稍慢：解析相对复杂，且缩进搞错一格，整个文档就废了。
- 适用场景：配置文件（如 K8s, CI/CD）、人工编写和维护 API 文档。

结论：两者在 OpenAPI 规范中是完全等价的。它们包含的 API 路径、参数模型、认证方式等信息一模一样。你需要做的，就是根据场景灵活切换。

你可能会想：“找个在线转换网站不就行了？”

小心踩坑！普通的文本转换工具往往不懂 OpenAPI 的业务逻辑。它们可能把你的枚举值（Enum）转丢，或者把 Swagger 2.0 的结构强行套在 OpenAPI 3.0 上。

我们需要的是一个既能“翻译格式”，又能“校验逻辑”的专业工具。这里强烈推荐 Apifox，它不仅是一个 API 协作平台，更是一个自带校验功能的OpenAPI 格式转换神器。

它支持 OpenAPI 3.0、3.1 和 Swagger 2.0 的任意互转。

接下来，我们演示如何利用 Apifox 将一份 JSON 格式的 Swagger 文档转换为 YAML（反之亦然）。

打开 Apifox，进入任意项目（或新建一个临时项目）。点击左侧的「项目设置」 -> 「导入数据」。

在数据源类型中，选择「OpenAPI (Swagger)」。

OpenAPI 格式互转：从 JSON 到 YAML，再从 YAML 回到 JSON

直接将你的文件拖入上传区。

重点来了：Apifox 的引擎非常智能，它会自动识别：

OpenAPI 格式互转：从 JSON 到 YAML，再从 YAML 回到 JSON

点击“确认导入”后，Apifox 会先对文档进行结构校验。如果原文档有语法错误，这里会直接报错提醒，避免你把错误的文档转来转去。

OpenAPI 格式互转：从 JSON 到 YAML，再从 YAML 回到 JSON

导入成功后，你的 API 文档就已经变成了 Apifox 中的可视化数据。现在，我们要把它“倒出来”。

选择「OpenAPI (Swagger)」作为导出类型

仔细看上图的配置项，你会发现 Apifox 还有一个隐藏神技：版本转换。

虽然工具很强大，但作为严谨的开发者，转换后建议做个简单的“体检”：

结构完整性：对比一下原文件，核心的 Paths（路径）数量对不对？
特殊字段检查：如果你用到了 $ref (引用) 或 oneOf/anyOf 等高级特性，检查在 Swagger 2.0 中是否被正确处理（因为 2.0 对这些支持有限）。
自动化验证：将导出的新文件再次导入 Apifox 或使用 CLI 工具验证，确保没有语法报错。