Swagger-Codegen 不使用供應商擴展 x-discriminator-value

Question

我正在嘗試使用 swagger-codegen 為架構規范生成 Java API 客戶端。 該架構使用供應商擴展x-discriminator-value來創建繼承模型。

例如，我使用了我在這里找到的 yaml 並轉換為 json 的模式規范（我用“spec”根包裝了結果，以便我可以將結果發送到在線代碼生成器，如下文所述）。

當我嘗試在本地或使用在線代碼生成器生成 Java 客戶端時，我發現沒有使用x-discriminator-value值完成去硅化。 相反，它是通過模型名稱完成的。 我在生成的JSON.java文件中看到了這一點，該文件包含從鑒別器到類的映射：

            classByDiscriminatorValue.put("PhoneSetting".toUpperCase(), PhoneSetting.class);
            classByDiscriminatorValue.put("SceneSetting".toUpperCase(), SceneSetting.class);
            classByDiscriminatorValue.put("TextSetting".toUpperCase(), TextSetting.class);

[要看到這一點，你可以post上述JSON來https://generator.swagger.io/api/gen/clients/java並檢查JSON.java文件。

據我所知，我應該知道關鍵應該是x-discriminator-value值。 例如，由於架構具有：

  "SceneSetting": {
      "description": "Scene Setting",
      "x-discriminator-value": "SCENE",
      "allOf": [
        {
          "$ref": "#/definitions/SectionSetting"
        }, 

那么我應該有一個映射

            classByDiscriminatorValue.put("SCENE".toUpperCase(), SceneSetting.class);

而不是 classByDiscriminatorValue.put("SceneSetting".toUpperCase(), SceneSetting.class);

我將不勝感激。

Answer 1

我建議遷移到 OpenAPI 3.0——它內置了對鑒別器映射的支持。 有OAS2-to-OAS3 轉換器可以幫助遷移，但您必須手動更新映射。

在 OpenAPI 3.0 中，鑒別器映射是在父模式中指定的（而不是在子模式中）。 為了便於閱讀，以下示例采用 YAML，您可以使用https://www.json2yaml.com將其轉換為 JSON。

openapi: 3.0.2

components:
  schemas:
    # Parent schema
    SectionSetting:
      type: object
      properties:
        ...
      discriminator:
        propertyName: PROP_NAME
        mapping:
          SCENE: SceneSetting
          ...

    # Child schema
    SceneSetting:
      description: Scene Setting
      allOf:
        - $ref: '#/components/schemas/SectionSetting'
        - ...

請確保使用 Swagger Codegen 3.x 版，因為 2.x 版不支持 OpenAPI 3.0。 您可以從 Maven Central 獲取最新的 3.x CLI JAR：
https://mvnrepository.com/artifact/io.swagger.codegen.v3/swagger-codegen-cli

Answer 2

在舊的 Swagger 2 上使用供應商擴展x-discriminator-value會帶來多重限制。

有關更多信息，請參閱openapi openapi-generator項目上的openapi-generator ：

// legacyDiscriminatorBehavior == True，這包含：
// - openapi 規范中 discriminMappedModelator 映射條目中模式映射信息的名稱 AND
// - 子 oneOf + anyOf 模式 + allOf 繼承自模式 AND 的后代模式中的 x 鑒別器值映射
// - allOf 繼承自模式 AND 的后代模式
// - 子 oneOf + anyOf 模式