提供文档和示例

除了机器可读的描述之外，OpenAPI 描述 (OAD) 还可以包含供开发人员阅读的传统文档。然后，自动文档生成器可以合并两者，并生成全面的、结构良好的参考指南，例如。

本页介绍如何充分利用 OpenAPI 中的特殊文档功能，例如降价语法或示例对象。

描述字段

OpenAPI 规范中的几乎每个对象都接受一个 description 字段，该字段可以为开发人员提供额外的信息，超出 API 描述中可以自动生成的范围。

例如，参数的名称、类型和有效值范围已存在于 API 描述中。 description 字段可以通过解释此参数的用途、每个值的效应或与其他参数的可能的交互作用来补充此信息。

paths:
  /audio/volume:
    put:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: integer
              minimum: 0
              maximum: 11
              description:
                Current volume for all audio output.
                0 means no audio output (mute). 10 is the maximum value. 11 enables
                the overdrive system (danger!).
                When set to 0 all other audio settings have no effect.
              ...

此外，路径项、操作 和 示例 对象通常具有较长的描述，它们接受一个 summary 字段，提供简短的描述。例如，文档生成器可以在完整路径列表中或页面标题中使用此字段。

在 YAML 中提供长描述

在 JSON 格式中，所有字符串都包含在引号中，因此它们从哪里开始和结束就很清楚了。然而，在 YAML 中，多行字符串可能会有点令人困惑。

首先，像上面这样的长描述在找到缩进较小的 YAML 行时结束。前导空格很重要！

此外，上面的示例使用纯模式表示字符串。它易于使用，因为它不需要任何特殊语法，但如果字符串包含冒号 : 或井号 # 字符，则可能会混淆 YAML 解析工具。在这些情况下，整个字符串必须包含在单引号或双引号中。

description: "Beware of lines containing colons and hashes like this: #"

如果需要对换行符的位置进行精确控制，则存在两种字符串模式，它们由描述第一行上的单个指示符字符启用。

  • 文字模式（管道 | 指示符字符）：源 YAML 文件中的换行符将在输出中保留。
  • 折叠模式（大于号 > 指示符字符）：换行符将被移除，因此输出为单个字符串。使用空行强制换行。

YAML 源 - 文字模式

description: |
  This is a string
  in multiple lines.

  And an extra one.

输出 - 文字模式

This is a string
in multiple lines.

And an extra one.

YAML 源 - 折叠模式

description: >
  This is a string
  in multiple lines.

  And an extra one.

输出 - 折叠模式

This is a string in multiple lines.
And an extra one.

文字模式和折叠模式不需要使用引号。

CommonMark 语法

description 字段允许使用 CommonMark 0.27 进行富文本格式化。本节是对最常用功能的语法快速总结。

除了下面列出的功能之外，还有更多功能可用（包括 HTML 标签），但是考虑到 OpenAPI 描述被设计为包含在更大的自动生成的文档中，使用更高级的格式通常非常复杂。

标题

# 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)

添加示例

最后，一些 OpenAPI 对象可以明确列出示例，而不是将它们嵌入到 description 字段中，从而允许工具进行自动处理。

这允许，除其他外

  • 在文档中对示例进行特殊渲染。
  • 示例对象可被模拟服务器用作返回值。

两个不同的字段提供了此功能：example 允许一个示例，而 examples 允许多个示例。每个对象中只能存在两个字段中的一个。

example 字段的內容（在 参数、媒体类型 和 架构 对象中找到）必须与父对象的格式匹配。

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

另一方面， examples 字段（在 参数 和 媒体类型 对象中找到）是一个映射，将示例名称与 示例对象 配对。此对象为示例提供 summary 和 description，以及实际代码（在 value 字段中或作为 externalValue 字段中的外部引用，但不能同时存在两者）。

这是 井字棋示例 API 的片段。

responses:
  "400":
    description: The provided parameters are incorrect
    content:
      text/html: # This is a Media Type Object
        schema:
          type: string
        examples:
          illegalCoordinates:
            value: "Illegal coordinates."
          notEmpty:
            value: "Square is not empty."
          invalidMark:
            value: "Invalid Mark (X or O)."

请注意，所有示例都与提供的模式匹配（它们都是字符串）。

总结

本页介绍了 OpenAPI 提供的功能，以帮助文档过程。更具体地说

  • 可以使用 description 字段在几乎所有地方添加文档。某些对象还允许使用 summary。
  • 文本可以使用CommonMark 语法进行富文本格式化，本页对其进行了快速总结。
  • 可以使用 example 或 examples 字段扩展文档，并提供示例代码。

下一页 说明如何指定可以访问 API 的服务器。