OpenAPI 3 YAML规范嵌入JSON格式对象类型消息示例方案咨询

首先明确一个基础常识：YAML是JSON的严格超集，任何合法的JSON结构本身就是合法的YAML内容，根本不需要额外做格式转换就能被正确解析。你之前的写法得到字符串类型，问题出在|这个块标量标记上——这个标记的作用就是强制YAML解析器把后续缩进的内容识别为纯文本，和内容本身是不是JSON没有关系。 #

方案1：直接内嵌原生JSON（零转换成本，最推荐） #

只要去掉|标记，直接把你手头的原生JSON内容缩进对齐放在value字段下即可，解析器会自动把它识别为标准对象/数组类型，完全符合OpenAPI的规范要求，解析结果和你转成YAML缩进写法完全一致。
写法示例：

examples:
  singlePet:
    summary: Single pet
    description: A request containing a single pet
    value:
      {
        "pets" : [
          {
            "petType" : "DOG",
            "name" : "Ben"
          }
        ]
      }

这种写法不需要对原始JSON做任何修改，复制粘贴就能用，兼顾YAML整体的可读性和JSON示例的复用性。

方案2：外部引用独立JSON文件（适合长示例） #

如果单份JSON示例内容很长，直接贴在主规范里会打断整体结构的可读性，可以把JSON示例单独存为独立的.json文件，通过externalValue字段引用文件相对路径即可。这种方式下示例值直接从JSON文件读取，天然是正确的对象类型，也不需要做任何格式转换。
写法示例：

examples:
  singlePet:
    summary: Single pet
    description: A request containing a single pet
    externalValue: './examples/single-pet.json'

方案3：JSON转YAML格式内嵌（兼容性最优） #

就是你目前在用的处理方式，把JSON通过工具或者手动转成YAML原生的键值缩进结构后嵌入，这种写法在所有OpenAPI工具链里的兼容性是最好的，YAML格式的可读性也最高，唯一的缺点是每次拿到JSON示例都需要做一次格式转换，多一步操作。 #

避坑提示：所有带|、>的块标量写法，以及用引号包裹JSON内容的写法，最终都会把示例值解析为字符串类型，不符合OpenAPI对对象类型示例的要求，不要使用。

内容的提问来源于stack exchange，提问作者KarelHusa