YAML中example字段格式化异常：Swagger转义符未消除及examples为空问题

我来帮你搞定这个困扰的转义符问题～你遇到的核心问题是手动把JSON字符串化后，YAML和Swagger都会保留转义符号，而且后来用example/examples还出现空结果，大概率是语法格式没踩对。下面给你几个靠谱的解决方案：

方案1：用YAML字面量块标量（推荐） #

YAML的|符号可以定义字面量块标量，它会原样保留换行和格式，内部的双引号完全不需要转义，完美适配你要展示的格式化JSON。写法如下：

log_level_per_component:
  type: object
  example: |
    {
      "Component1": "Info",
      "Component2": "Debug",
      "Component3": "Fatal",
      ...
    }

这样写的话，Swagger UI渲染出来的示例就是干净的格式化JSON，不会带任何转义符，和你期望的效果完全一致。

方案2：用OpenAPI 3.x的examples复数字段（规范写法） #

如果你用的是OpenAPI 3.0及以上版本，更推荐用examples字段，直接把示例写成YAML对象（Swagger会自动转成JSON），彻底避免字符串化的麻烦：

log_level_per_component:
  type: object
  examples:
    sample_log_levels:
      summary: 示例日志级别配置
      value:
        Component1: "Info"
        Component2: "Debug"
        Component3: "Fatal"

这种写法不仅没有转义问题，还能给示例加描述，Swagger UI展示的时候会更清晰友好。

针对你遇到的「空结果」问题排查 #

你说用example和examples都得到空结果，大概率是YAML语法错误导致的，检查这几点：

• 确保缩进用空格（不要用制表符），YAML对缩进非常敏感，每层缩进保持2或4个空格一致
• 如果用块标量|，后面的JSON内容要比example:多缩进一层
• 用examples时，必须嵌套在value字段下，不能直接写示例内容

按照上面的方法调整后，应该就能得到你想要的干净示例啦～

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