継承とポリモーフィズム

モデルの構成

APIでは、共通のプロパティを共有するモデルスキーマを持つことができます。これらのプロパティを各スキーマに対して繰り返し記述する代わりに、共通のプロパティセットとスキーマ固有のプロパティの合成としてスキーマを記述できます。OpenAPIバージョン3では、これをallOfキーワードで行います。

1
components:
2
  schemas:
3
    BasicErrorModel:
4
      type: object
5
      required:
6
        - message
7
        - code
8
      properties:
9
        message:
10
          type: string
11
        code:
12
          type: integer
13
          minimum: 100
14
          maximum: 600
15
    ExtendedErrorModel:
16
      allOf: # Combines the BasicErrorModel and the inline model
17
        - $ref: "#/components/schemas/BasicErrorModel"
18
        - type: object
19
          required:
20
            - rootCause
21
          properties:
22
            rootCause:
23
              type: string

上記の例では、ExtendedErrorModelスキーマは独自のプロパティとBasicErrorModelから継承されたプロパティを含んでいます。注：データを検証する際、サーバーとクライアントは結合されたモデルをそれが構成する各モデルに対して検証します。競合するプロパティ（同じ名前だが異なるデータ型を持つプロパティなど）の使用は避けることをお勧めします。

ポリモーフィズム

APIでは、いくつかの代替スキーマで記述できるリクエストとレスポンスを持つことができます。OpenAPI 3.0では、そのようなモデルを記述するためにoneOfまたはanyOfキーワードを使用できます。

1
components:
2
  responses:
3
    sampleObjectResponse:
4
      content:
5
        application/json:
6
          schema:
7
            oneOf:
8
              - $ref: '#/components/schemas/simpleObject'
9
              - $ref: '#/components/schemas/complexObject'
10
  …
11
components:
12
  schemas:
13
    simpleObject:
14
      …
15
    complexObject:
16
      …

この例では、レスポンスペイロードにはsimpleObjectまたはcomplexObjectのいずれかを含めることができます。

ディスクリミネーター

APIコンシューマがオブジェクトのタイプを検出するのを助けるために、モデル定義にdiscriminator/propertyNameキーワードを追加できます。このキーワードは、データタイプ名を指定するプロパティを指します。

1
components:
2
  responses:
3
    sampleObjectResponse:
4
      content:
5
        application/json:
6
          schema:
7
            oneOf:
8
              - $ref: '#/components/schemas/simpleObject'
9
              - $ref: '#/components/schemas/complexObject'
10
            discriminator:
11
              propertyName: objectType
12
  …
13
  schemas:
14
    simpleObject:
15
      type: object
16
      required:
17
        - objectType
18
      properties:
19
        objectType:
20
          type: string
21
      …
22
    complexObject:
23
      type: object
24
      required:
25
        - objectType
26
      properties:
27
        objectType:
28
          type: string
29
      …

私たちの例では、ディスクリミネーターはデータ型名を含むobjectTypeプロパティを指しています。ディスクリミネーターはanyOfまたはoneOfキーワードとのみ使用されます。anyOfまたはoneOfの下に記述されるすべてのモデルがディスクリミネーターが指定するプロパティを含むことが重要です。これは、例えば、上記のコードでsimpleObjectとcomplexObjectの両方がobjectTypeプロパティを持つ必要があることを意味します。このプロパティはこれらのスキーマで必須です。

1
schemas:
2
    simpleObject:
3
      type: object
4
      required:
5
        - objectType
6
      properties:
7
        objectType:
8
          type: string
9
      …
10
    complexObject:
11
      type: object
12
      required:
13
        - objectType
14
      properties:
15
        objectType:
16
          type: string
17
      …

discriminatorキーワードは、さまざまなAPIコンシューマが使用できます。考えられる例の1つはコード生成ツールです。これらはディスクリミネーターを使用して、ディスクリミネータープロパティの値に基づいてリクエストデータを適切なオブジェクト型にキャストするプログラムステートメントを生成できます。

型名のマッピング

ディスクリミネーターが参照するプロパティは、ターゲットスキーマの名前を含むことが暗示されています。上記の例では、objectTypeプロパティはsimpleObjectまたはcomplexObject文字列のいずれかを含む必要があります。プロパティ値がスキーマ名と一致しない場合、値を名前にマッピングできます。これを行うには、discriminator/mappingキーワードを使用します。

1
components:
2
  responses:
3
    sampleObjectResponse:
4
      content:
5
        application/json:
6
          schema:
7
            oneOf:
8
              - $ref: '#/components/schemas/Object1'
9
              - $ref: '#/components/schemas/Object2'
10
              - $ref: 'sysObject.json#/sysObject'
11
            discriminator:
12
              propertyName: objectType
13
              mapping:
14
                obj1: '#/components/schemas/Object1'
15
                obj2: '#/components/schemas/Object2'
16
                system: 'sysObject.json#/sysObject'
17
  …
18
  schemas:
19
    Object1:
20
      type: object
21
      required:
22
        - objectType
23
      properties:
24
        objectType:
25
          type: string
26
      …
27
    Object2:
28
      type: object
29
      required:
30
        - objectType
31
      properties:
32
        objectType:
33
          type: string
34
      …

この例では、obj1の値は同じ仕様で定義されているObject1モデルにマッピングされ、obj2はObject2に、値systemは外部ファイルにあるsysObjectモデルと一致します。これらのすべてのオブジェクトは、それぞれ値"obj1"、"obj2"、または"system"を持つobjectTypeプロパティを持つ必要があります。

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