虽然机器可读是 OpenAPI 文档的一大特点，但是，它同时也提供了传统的文档形式，让开发者容易阅读和测试。
下面就通过介绍文档字段和示例对象，来说明 OpenAPI 的传统文档能力。
文档字段
OpenAPI 的文档字段包含：描述字段（description）和摘要字段（summary）。
在 OpenAPI 文档中，除了自动产生的描述信息，几乎所有的对象都包含了一个描述字段，为对象提供额外的描述信息，方便开发者阅读和理解。
例如，假设在 API 中定义了一个参数的名字、类型和取值范围。接下来，我们可以通过描述字段，进一步补充一些描述信息，说明参数的目的，参数不同取值的效果及联系。
paths:
/vedio/volume:
put:
requestBody:
required: true
content:
application/json:
schema:
type: integer
minimum: 0
maximum: 10
description:
当前视频的输出音量.
0 表示音量最小值 (静音)。 10 表示音量的最大值。
当设置为0时，其他音量设置无效。
...
此外，还有一些对象（Path Item，Operation 和 Example 对象）包含了摘要字段，可以为对象提供简短描述。
长描述
与 JSON 格式不同，YAML 的字符串通常只是一行文字，不需要加注引号。但是，如果字符串中出现了特殊字符，影响到文档的解析，就需要用单引号或双引号把字符串内容括起来。
如果描述信息很长，还要控制好内容的换行。在 YAML 文件格式中，有两类换行模式：
- 字面模式（Literal mode）：使用管道符
|表示。文件输出的换行形式与源文件编写的形式一致。 - 折叠模式（Folded mode）：使用大于号
>表示。文档输出格式会移除源文件中添加的所有换行符，成为一个单一的字符串。但是，在编写源文件时，可以使用空行强制换行。
字面模式换行
description: |
这是一个多行的字
符串。
这是另一行字符串。
字面模式换行效果
这是一个多行的字
符串。
这是另一行字符串。
折叠模式换行
description: >
这是一个多行的字
符串。
这是另一行字符串。
折叠模式换行效果
这是一个多行的字符串。
这是另一行字符串。
CommonMark 句法
description 字段还可以使用丰富的文本格式，这些文本格式需要遵循CommonMark 0.27 规范。
下面是一些常用示例：
标题
# Level 1
## Level 2
### Level 3
强调
*Emphasis*
**Strong Emphasis**
***Both***
列表
- Item 1
- Item 2
- Item 2.1
代码
An inline `code span`.
```
A fenced code block
```
链接
[Link text](Link URL)
示例对象
如果 API 文档能够提供输入、输出参数的示例值，一定会大有裨益。你可能会想到把示例放到描述字段，还可以利用丰富的格式化手段更好地呈现。但是，OpenAPI 为我们提供了示例对象（Sample Object）用于展现示例值。使用示例对象的好处是：
- OpenAPI 工具能够自动化处理示例对象
- OpenAPI 文档中的示例对象能够进行独特展示
- 模拟测试服务可以把示例对象用作返回值
schema:
coordinate:
type: integer
minimum: 1
maximum: 3
example: 1
