跳到内容

组件部分

通常，多个 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 作为各种可重用定义——schema（数据模型）、parameters、responses、examples 等——的容器。`components` 中的定义本身对 API 没有直接影响，除非您从 `components` 外部显式引用它们。也就是说，`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` 中的定义是例外，它们直接按名称引用（请参阅 认证）。

组件示例

下面是一个包含可重用数据 schema、参数和响应的 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'

参考

Components 对象

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

© . All rights reserved.