元件章節

通常，多個 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

元件名稱是用來透過 API 規格的其他部分中的 $ref 來參考元件

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'

參考

元件物件

沒有找到您要尋找的內容嗎？詢問社群
發現錯誤？讓我們知道