繼承與多型

模型組成

在您的 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
      …

各種 API 使用者可以使用 discriminator 關鍵字。一個可能的範例是程式碼產生工具：它們可以使用鑑別器產生程式語句，根據鑑別器屬性值將請求資料轉換為適當的物件類型。

對應類型名稱

這表示鑑別器參照的屬性包含目標結構描述的名稱。在上面的範例中，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 模型。所有這些物件都必須具有 objectType 屬性，其值分別為 "obj1"、"obj2" 或 "system"。

找不到您要尋找的內容嗎？向社群提問
發現錯誤嗎？請告訴我們