在 Swagger 中使用 JSON 和 YAML 有什么实际区别？答案

【问题标题】：What is the practical different between the usage of JSON and YAML in Swagger?在 Swagger 中使用 JSON 和 YAML 有什么实际区别？
【发布时间】：2018-04-09 23:31:02
【问题描述】：

JSON 似乎包含路径信息和 http 请求动词，而 YAML 似乎只是单独定义了一个树结构。

它们之间有什么区别？还是我在这里混合了不同的概念/层次结构？新手招摇，刚开始学习。

如果 YAML 是 JSON 的超集，这里添加的超集具体是什么 - 它是 URL 路径和 HTTP 动词吗？是否添加 example 也是 YAML 为 Swagger 添加到 JSON 的内容？

【问题讨论】：

标签： json yaml swagger

【解决方案1】：

JSON 不支持 cmets，而 YAML 支持！

【讨论】：

我在想为什么我应该使用一个而不是另一个，直到我读到这一点。评论在开发中可能非常有用（即：我可以添加待办事项！）。我猜它可以被视为文档（yaml）与数据（json）之间的区别
虽然，imo，任何 cmets 都应该被烘焙到文档本身，而不是在 YAML 规范级别。

【解决方案2】：

如果换个角度看，YAML 比 JSON 更简洁、更易读写。

【讨论】：

【解决方案3】：

根据OpenAPI Specification，

符合 OpenAPI 规范的 OpenAPI 文档本身就是一个 JSON 对象，可以用 JSON 或 YAML 格式表示。

所以在功能方面，使用 JSON 或 YAML 没有区别。 YAML 作为 JSON 的超集在这里添加的只是一种不同的语法。使用规范中的示例，这两个文档是相同的：

{
  "servers": [
    {
      "url": "https://development.gigantic-server.com/v1",
      "description": "Development server"
    },
    {
      "url": "https://staging.gigantic-server.com/v1",
      "description": "Staging server"
    },
    {
      "url": "https://api.gigantic-server.com/v1",
      "description": "Production server"
    }
  ]
}

和

servers:
- url: https://development.gigantic-server.com/v1
  description: Development server
- url: https://staging.gigantic-server.com/v1
  description: Staging server
- url: https://api.gigantic-server.com/v1
  description: Production server

第一个文档是有效的 JSON 和有效的 YAML（因为 YAML 是 JSON 的超集）。第二个文档是有效的 YAML，并且在结构上与第一个文档相同。

所以要回答关于 YAML 超集在这里添加了什么的问题：它添加了不同的语法来指定相同的结构。仅此而已。

_{^{YAML 确实包含一些无法映射到 JSON 的特性，但它们在这里无关紧要，因为 Swagger/OpenAPI 不使用它们。}}

【讨论】：