API 入门（5）OpenAPI 的 Paths 对象

在上一篇文章中，我们了解了 OpenAPI 文档对象的最小组成结构，但是没有定义任何 API，可以说没有使用价值。接下来，我们就动手在文档中描述一个 API.

在 OpenAPI 规范中，把 API 端点（API Endpoints）称为 Paths. API 支持的所有操作，都包含在 Paths 对象中。

在 Paths 对象中，每一个字段都是 Path Item 对象类型，Paht Item 对 API 端点进行描述。Paths 对象可以包含多个 Path Item 对象，每一个Path Item 对象都是一个独立的字段，而不是把所有的 Path Item 都放到一个数组中。这样做的好处是，可以通过 JSON 或 YAML 的语法规则，保证端点的唯一性。

每个 Pahts 的第一个字符必须使用 / ，因为 Paths 需要附加到服务器 URL 后面的。

在 Path Item 对象中，使用 Operation 对象对 HTTP 的方法名，如 GET、PUT 或者 DELETE，进行描述。

paths:
  /hello:
    get:
      ...
    put:
      ...

Operation 对象可以使用 summary、description、parameters、response 字段进行详细描述。

paths:
  /hello:
    get:
      summary: 打招呼
      description: 向大家问好！
      parameters:
        ...
      responses:
        ...

调用 API 可能返回的的响应对象，用 Responses 对象来表示。而对于每个具体的响应，使用 HTTP 的响应状态码作为字段名称来表示。需要注意的是，状态码数字要放到引号里。

paths:
  /hello:
    get:
      responses:
        "200":
          ...
        "404":
          ...
         "5xx":
          ...

每个 Response 对象必须强制包含 description 字段，对响应对象进行描述。而最重要的 content 字段包含了响应的内容。

paths:
  /hello:
    get:
      responses:
        "200":
          description: 打招呼，成功了。
          content:
            ...

经过上面对讲解，下面对代码片段就容易理解了：

openapi: 3.1.0
info:
  title: OpenAPI 文档示例
  description: |
    本文档中的 API 描述仅用于学习。
  version: 1.0.0
paths:
  # 这里是注释
  /hello:
    get:
      summary: 你好，读者
      description: 这里是对端点的描述，打个招呼
      responses:
        "200":
          description: "OK"
          content: