OpenAPI YAML的description字段中|、>、>-有什么核心区别？

首先要明确：这三个写法的差异完全来自通用YAML解析规则，不是OpenAPI的自定义语法——OpenAPI的配置文件本身基于YAML格式，对多行文本的支持只是继承了YAML的原生能力，三者的行为在所有YAML解析器里都是统一的。
三者的核心差异围绕两个维度展开：文本内部的换行处理规则、文本末尾的换行处理规则。 #

各语法的具体行为 #

1. description: |（字面块标量） #

这是规则最直接的多行语法：

• 完整保留文本块内部的所有硬换行、行首缩进，不会把连续书写的行拼接成一行
• 默认会在整个文本的末尾保留1个换行符

举个实际解析的例子：

description: |
  接口入参说明：
  - id: 用户唯一标识
  - name: 用户名称

最终解析得到的description值为：

接口入参说明：
- id: 用户唯一标识
- name: 用户名称
\n

（最后多出的\n就是默认保留的末尾换行）
这种写法最适合需要严格保留排版的内容，比如带Markdown列表、代码块的接口说明——毕竟Markdown的列表、分段完全依赖硬换行，用|写出来的描述渲染出来格式不会乱。 #

2. description: >（折叠块标量） #

这个语法本质是为了方便开发者在YAML里写长文本时手动折行读文件，不会因为把长句子都挤在一行导致编辑的时候看不清，最终输出的文本是连续的段落流：

• 把文本块内部所有单个连续的硬换行替换成普通空格，仅当出现连续空行时，才会保留1个硬换行作为段落分隔
• 同样默认在文本末尾保留1个换行符

用和上面一样的内容举例：

description: >
  接口入参说明：
  - id: 用户唯一标识
  - name: 用户名称

最终解析得到的description值为：

接口入参说明： - id: 用户唯一标识 - name: 用户名称
\n

可以看到所有换行都被换成了空格，原本的列表完全失效，变成了一整行的文本。这个语法适合写大段没有格式要求的自然语言说明，比如接口的整体业务背景描述，只要段落流畅就行，不需要保留硬排版。 #

3. description: >-（带修剪修饰的折叠块标量） #

这个语法是在>的规则基础上，加了一个末尾修剪的修饰符：

• 完全继承>的换行折叠规则：单个换行换空格，空行保留硬换行
• 额外去掉整个文本末尾的所有换行符，不会像前两个语法那样在最后留多余的\n

还是用上面的例子：

description: >-
  接口入参说明：
  - id: 用户唯一标识
  - name: 用户名称

最终解析得到的description值为：

接口入参说明： - id: 用户唯一标识 - name: 用户名称

对比上面>的解析结果，少了最后那个多余的末尾换行。

补充说明：所有YAML块标量后面都可以加两个可选的修饰符：-代表「修剪末尾所有换行」，+代表「保留文本块里所有的末尾空行」；如果不加修饰符，默认行为就是「在文本末尾保留1个换行」。比如|-就是|基础上修剪末尾换行的版本，规则和>-是完全对应的。

OpenAPI 场景下的选型建议 #

• 如果description里要带Markdown格式（列表、代码块、强制换行的强调内容），直接选|，避免因为换行折叠导致格式渲染失效
• 如果是纯段落的业务说明，不想在最终生成的文档里出现多余的末尾空行，选>-会更干净
• 千万别用>写带格式的Markdown内容，这是OpenAPI开发里非常常见的格式踩坑点

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