API 入门 (31) 使用 OpenAPI 描述 REST A

我们已经介绍了如何使用 OpenAPI 规范， 对添加自行车和查询自行车两个操作进行了描述。如果你细心阅读，就会发现：这两个操作都对自行车资源进行了描述。也就是说，同一个资源，被描述了两次。每个人都不想重复发明轮子，本文就来解决这个问题。

定义组件

在API 入门 (8) OpenAPI 组件对象一文中，简要介绍了组件对象。我们可以把相同的数据描述，放到组件集合属性中，并在需要使用该数据的地方进行引用。

接下来，我们就在组件集合属性中，定义一个自行车资源组件。

因为自行车资源的数据结构定义是一个 schema ，所以，我们需要在 组件集合属性(components) 下的 schemas 属性中，定义一个自行车的 schema.

openapi: '3.0.2'
info:
  title: 自行车在线商城 REST API 文档。
  version: '1.0'
servers:
  - url: https://api.server.test/v1
[...]
components:
  schemas:
    bike:
      type: object
      description: 自行车
      required:
        - reference
        - name
        - price
      properties:
        reference:
          description: 自行车唯一标识
          type: string
        name:
          type: string
        price:
          type: number
        weight:
          type: number
        description:
          type: string

• components：表示可重用的组件集合对象
• schemas：表示可重用的 schema
• bike：表示可重用的 schema 的名称
• object：表示一个 JSON 对象

引用组件

我们定义了可重用的组件后，就可以在需要使用这个组件的地方进行引用了，不需要再重复定义。

在添加自行车的时候，进行引用。

  responses:
    "200":
      description: 已添加的自行车信息
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/bike"

在查询自行车的时候，进行引用。

responses:
  "200":
    description: 满足查询条件的自行车
    content:
      application/json:
        schema:
          type: array
          description: 自行车集合
          items:
            $ref: "#/components/schemas/bike"

在引用组件时，我们使用了 $ref 属性，该属性的值表示组件所在的路径。上面的两个引用，与所引用的组件位于同一个文档内，称为本地引用。当然，在一个文档中，也可以引用其他文档中的组件。

小结

在 OpenAPI 文档中，使用可重用组件，能够避免对同一数据的重复描述。这样做，不仅可以使文档更精简，也增强了文档的可维护性。