API 入门（9）OpenAPI 文档字段和示例

虽然机器可读是 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)
![Alt text](Image URL)

示例对象

如果 API 文档能够提供输入、输出参数的示例值，一定会大有裨益。你可能会想到把示例放到描述字段，还可以利用丰富的格式化手段更好地呈现。但是，OpenAPI 为我们提供了示例对象（Sample Object）用于展现示例值。使用示例对象的好处是：

OpenAPI 工具能够自动化处理示例对象
OpenAPI 文档中的示例对象能够进行独特展示
模拟测试服务可以把示例对象用作返回值

schema:
  coordinate:
    type: integer
    minimum: 1
    maximum: 3
    example: 1

API 入门（9）OpenAPI 文档字段和示例