コンテンツにスキップ

コンポーネントセクション

多くの場合、複数の 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 つ以上の名前付きコンポーネント (定義) が含まれます

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

このようにすることで、外部ファイルのパスをすべての参照で繰り返す代わりに、外部定義のローカルな「エイリアス」を定義することができます。参照されるファイルの場所が変更された場合、すべての参照ではなく、1 箇所（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'

参照

コンポーネントオブジェクト

お探しのものが見つかりませんでしたか？ コミュニティに質問する
間違いを見つけましたか？ お知らせください