重用描述

正如经常发生的那样，通过前面的页面构建的示例已经变得太大，难以管理。此页面介绍了一种机制，可以通过重用其部分内容来消除 OpenAPI 描述 (OAD) 中的冗余。

Components 对象

可以通过根 OpenAPI 对象中的 components 字段访问的 Components 对象包含要在描述的其他部分中重用的对象的定义。

OpenAPI 对象在 OpenAPI 描述的结构页面中进行了解释。
Schema 对象在消息体的内容页面中进行了解释。
Response 对象在 API 端点页面中进行了解释。
Parameter 对象在操作的参数和有效负载页面中进行了解释。

OAD 中的大多数对象都可以用对组件的引用来代替，从而大大减少了 OAD 的大小和维护成本（就像编程语言中的方法一样）。

但是，并非所有对象都可以被引用，只有那些列为 Components 对象的字段的对象，例如 schemas、responses 和 parameters（仅举几例）。

Components 对象中的每个字段都是一个映射，将组件名称与要重用的对象配对。这些对象的类型必须与父字段匹配，例如 schemas 映射中的对象必须是 Schema 对象。

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

以上示例定义了两个组件

coordinate 是一个 schema 组件，可以在需要 Schema 对象的任何地方使用。
rowParam 是一个参数组件，可以在需要 Parameter 对象的任何地方使用。

下一节将解释如何引用这些组件。

引用对象

任何 Components 对象支持的类型的 OpenAPI 对象都可以用指向组件的引用对象代替。

引用对象实际上是 JSON 引用：它们包含一个名为 $ref 的单个字段，其字符串值为指向被引用对象的 URI

  $ref: 'https://gigantic-server.com/schemas/Monster/schema.yaml'

引用可以是绝对的或相对的，它们可以包含一个片段标识符

$ref: './another_file.yaml#rowParam'

要完成上一节中的示例

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:
  /board/{row}/{column}:
    parameters:
      - $ref: "#/components/parameters/rowParam"
      - $ref: "#/components/parameters/columnParam"

请注意所有引用如何指向同一文档（正在处理的文档）内的不同片段。

另请注意 coordinate schema 如何被使用了两次（在 rowParam 和 columnParam 参数中），以及这两个参数如何从 /board/{row}/{column} 路径中引用。

俄罗斯方块示例

完整的俄罗斯方块示例 API（出于简洁起见，此处未包含）大量使用组件。例如，请注意不同的端点如何在成功时返回 #/components/schemas/status，或在错误时返回 #/components/schemas/errorMessage。

总结

每当相同的 JSON 或 YAML 部分在 OAD 中重复出现时，将其转换为组件并在其他地方引用它可能很有价值。

此外，引用对象允许将描述拆分为多个文档，以保持它们的组织性，并使其每个文档的大小易于管理。

此页面已显示

可重用的 Components 对象可以通过使用根 OpenAPI 对象的 components 字段来定义。
可以使用 $ref 从任何需要相同类型对象的的地方引用组件。
引用实际上是 URI，因此它们非常灵活。

下一页解释如何在 OpenAPI 描述中包含文档和示例。