组件部分

通常，多个 API 操作具有一些公共参数或返回相同的响应结构。为了避免代码重复，您可以将公共定义放置在全局的 components 部分中，并使用 $ref 引用它们。在下面的示例中，User 对象的重复定义被替换为单个组件和对该组件的引用。之前

1
paths:
2
  /users/{userId}:
3
    get:
4
      summary: Get a user by ID
5
      parameters: ...
6
      responses:
7
        "200":
8
          description: A single user.
9
          content:
10
            application/json:
11
              schema:
12
                type: object
13
                properties:
14
                  id:
15
                    type: integer
16
                  name:
17
                    type: string
18
  /users:
19
    get:
20
      summary: Get all users
21
      responses:
22
        "200":
23
          description: A list of users.
24
          content:
25
            application/json:
26
              schema:
27
                type: array
28
                items:
29
                  type: object
30
                  properties:
31
                    id:
32
                      type: integer
33
                    name:
34
                      type: string

之后

1
paths:
2
  /users/{userId}:
3
    get:
4
      summary: Get a user by ID
5
      parameters: ...
6
      responses:
7
        "200":
8
          description: A single user.
9
          content:
10
            application/json:
11
              schema:
12
                $ref: "#/components/schemas/User"
13
  /users:
14
    get:
15
      summary: Get all users
16
      responses:
17
        "200":
18
          description: A list of users.
19
          content:
20
            application/json:
21
              schema:
22
                type: array
23
                items:
24
                  $ref: "#/components/schemas/User"
25

26
components:
27
  schemas:
28
    User:
29
      type: object
30
      properties:
31
        id:
32
          type: integer
33
        name:
34
          type: string

组件结构

components 用作各种可重用定义的容器 - 模式（数据模型）、参数、响应、示例等。components 中的定义除非您从 components 外部显式引用它们，否则对 API 没有直接影响。也就是说，components 不是适用于所有操作的参数和响应；它们只是要在其他地方引用的信息片段。在 components 下，定义按类型分组 - schemas、parameters 等。以下示例列出了可用的子部分。所有子部分都是可选的。

1
components:
2
  # Reusable schemas (data models)
3
  schemas: ...
4

5
  # Reusable path, query, header and cookie parameters
6
  parameters: ...
7

8
  # Security scheme definitions (see Authentication)
9
  securitySchemes: ...
10

11
  # Reusable request bodies
12
  requestBodies: ...
13

14
  # Reusable responses, such as 401 Unauthorized or 400 Bad Request
15
  responses: ...
16

17
  # Reusable response headers
18
  headers: ...
19

20
  # Reusable examples
21
  examples: ...
22

23
  # Reusable links
24
  links: ...
25

26
  # Reusable callbacks
27
  callbacks: ...

每个子部分包含一个或多个命名的组件（定义）

1
components:
2
  schemas:
3
    User:
4
      type: object
5
      ...
6
    Pet:
7
      type: object
8
      ...

组件名称只能包含以下字符

1
A..Z a..z 0..9 . _ -

有效名称示例

1
User
2
New_User
3
org.example.User
4
401-Unauthorized

组件名称用于通过 $ref 从 API 规范的其他部分引用组件

1
$ref: "#/components/<type>/<name>"

例如

1
$ref: "#/components/schemas/User"

一个例外是 securitySchemes 中的定义，它们直接按名称引用（请参阅身份验证）。

组件示例

下面是一个 components 的示例，其中包含可重用的数据模式、参数和响应。其他组件类型（链接、示例等）的定义类似。

1
components:
2
  #-------------------------------
3
  # Reusable schemas (data models)
4
  #-------------------------------
5
  schemas:
6
    User: # Can be referenced as '#/components/schemas/User'
7
      type: object
8
      properties:
9
        id:
10
          type: integer
11
          format: int64
12
        name:
13
          type: string
14

15
    Error: # Can be referenced as '#/components/schemas/Error'
16
      type: object
17
      properties:
18
        code:
19
          type: integer
20
        message:
21
          type: string
22

23
  #-------------------------------
24
  # Reusable operation parameters
25
  #-------------------------------
26
  parameters:
27
    offsetParam: # Can be referenced via '#/components/parameters/offsetParam'
28
      name: offset
29
      in: query
30
      description: Number of items to skip before returning the results.
31
      required: false
32
      schema:
33
        type: integer
34
        format: int32
35
        minimum: 0
36
        default: 0
37

38
    limitParam: # Can be referenced as '#/components/parameters/limitParam'
39
      name: limit
40
      in: query
41
      description: Maximum number of items to return.
42
      required: false
43
      schema:
44
        type: integer
45
        format: int32
46
        minimum: 1
47
        maximum: 100
48
        default: 20
49

50
  #-------------------------------
51
  # Reusable responses
52
  #-------------------------------
53
  responses:
54
    404NotFound: # Can be referenced as '#/components/responses/404NotFound'
55
      description: The specified resource was not found.
56

57
    ImageResponse: # Can be referenced as '#/components/responses/ImageResponse'
58
      description: An image.
59
      content:
60
        image/*:
61
          schema:
62
            type: string
63
            format: binary
64

65
    GenericError: # Can be referenced as '#/components/responses/GenericError'
66
      description: An error occurred.
67
      content:
68
        application/json:
69
          schema:
70
            $ref: "#/components/schemas/Error"

外部定义的组件

components 中的单个定义可以使用内联方式（如前面的示例）或使用对外部定义的 $ref 引用来指定

1
components:
2
  schemas:
3
    Pet:
4
      $ref: "../models/pet.yaml"
5
      # Can now use use '#/components/schemas/Pet' instead
6
    User:
7
      $ref: "https://api.example.com/v2/openapi.yaml#/components/schemas/User"
8
      # Can now use '#/components/schemas/User' instead
9

10
  responses:
11
    GenericError:
12
      $ref: "../template-api.yaml#/components/responses/GenericError"
13
      # Can now use '#/components/responses/GenericError' instead

这样，您可以为外部定义定义本地“别名”，您可以使用它们而不是在所有引用中重复外部文件路径。如果被引用文件的位置发生变化，您只需在一个地方（在 components 中）更改它，而不是在所有引用中更改它。

与 OpenAPI 2.0 的差异

OpenAPI 2.0 为可重用组件提供了单独的部分 - definitions、parameters、responses 和 securityDefinitions。在 OpenAPI 3.0 中，它们都被移到了 components 内部。此外，definitions 被重命名为 schemas，而 securityDefinitions 被重命名为 securitySchemes（请注意不同的拼写：schem_A_s 与 securitySchem_E_s）。引用也相应地更改以反映新的结构

1
OpenAPI 2.0                    OpenAPI 3.0
2
'#/definitions/User'         → '#/components/schemas/User'
3
'#/parameters/offsetParam'   → '#/components/parameters/offsetParam'
4
'#/responses/ErrorResponse'  → '#/components/responses/ErrorResponse'

参考

组件对象

没有找到您要找的内容？咨询社区
发现错误？请告知我们