往期回顾：

• API 入门（1）什么是 API
• API 入门（2）API 的分类
• API 入门（3）API 简史
• API 入门（4）OpenAPI 文档结构
• API 入门（5）OpenAPI 的 Paths 对象
• API 入门（6）OpenAPI 响应内容
• API 入门（7）OpenAPI 参数和载荷

在以前的文章中，我们使用的文档片段示例非常简单，但是，在实际的 API 开发过程中，API 的输入和输出内容会变得非常复杂。而且，不同的 API 操作经常会共用相同的请求体或响应内容的描述。那么，这该如何处理呢？

如果你对面向对象编程有一定的了解，你会想到，可以把相同的内容描述组织在一个地方，在其他使用的地方进行引用。下面我们就介绍 OpenAPI 提供的类似方法——组件对象。

组件集合对象（Components Object）

在 OpenAPI 中，组件集合对象包含了所有可重用的对象的定义。在 API 文档的其他部分，可以对这些组件对象进行引用。组件集合对象位于 OpenAPI 根对象下，在 API 文档中，使用 components 字段表示。

使用组件对象替代重复使用的内容描述，不仅可以提升效率，还能缩减文档的大小，增强文档的可维护性。

那么，有哪些对象可以放到组件集合对象中呢？OpenAPI 规范定义了如下固定的组件对象：

如果上述组件对象不能不满足需要，可以进行自定义扩展，详细参考官方文档。

组件集合对象是一个 Map 结构，使用组件对象的名称，与具体可重用的内容进行关联。当然，组件对象的类型必须与父级字段（如schemas、parameters等）匹配。示例如下：

components:
  schemas:
    coordinate:
      type: integer
      minimum: 1
      maximum: 3
  parameters:
    rowParam:
      name: row
      in: path
      required: true

上面的示例中定义了两个组件：

• coordinate：schema 类型的组件。
• rowParam：parameter 类型的组件。

引用对象（Reference Object）

在组件集合对象中，所有定义其中的组件对象，如果没有在文档其他部分被引用，就不会对 API 文档的描述产生影响。

在 OpenAPI 文档中，使用引用对象（Reference Object）与组件对象进行关联。示例如下：

components:
  schemas:
    coordinate:
      type: integer
      minimum: 1
      maximum: 3
  parameters:
    rowParam:
      name: row
      in: path
      required: true
      schema:
        $ref: "#/components/schemas/coordinate"
    columnParam:
      name: column
      in: path
      required: true
      schema:
        $ref: "#/components/schemas/coordinate"
paths:
  /hi/{row}/{column}:
    parameters:
      - $ref: "#/components/parameters/rowParam"
      - $ref: "#/components/parameters/columnParam"

在上面的例子中，两个参数类型的组件对象 rowParam 和 columnParam 都引用了 coordinate 组件对象。接下来，在路径对象中，分别引用了参数类型的 rowParam 和 columnParam 两个组件对象，作为路径参数的描述。

小结

在编写 OpenAPI 文档的时候，只要发现同一块 JSON 或 YAML 文档片段被重复使用，就可以考虑把他们转换成组件。

组件可以跨文档进行引用，也就是说，在一个文档里引用另一个文档的组件。这样，我们就可以灵活地管理文档，并且能够对文档的大小进行合理控制。

在下一篇文章里，我们将介绍如何在 API 文档中添加描述和示例，让文档的可读性更高。