Swagger-Codegen 不使用供应商扩展 x-discriminator-value

Question

我正在尝试使用 swagger-codegen 为模式规范生成 Java API 客户端。 该架构使用供应商扩展 x-discriminator-value 创建继承模型。

例如，我使用了作为 yaml here 找到的模式规范并转换为 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

在旧版 Swagger 2 上使用供应商扩展 x-discriminator-value 会带来多项限制。

有关更多信息，请参阅 openapi-generator 项目中的 CodegenDiscriminator.java：

// legacyDiscriminatorBehavior == True，这包含：
// - 您的 openapi 规范中 discriminMappedModelator 映射条目中模式映射信息的名称 AND
// - 子 oneOf + anyOf 模式 + allOf 继承自身模式的后代模式中的 x 鉴别器值映射 AND
// - allOf 继承自身架构的后代架构 AND
// - 子 oneOf + anyOf 模式

Answer 2

我建议迁移到 OpenAPI 3.0 - 它内置了对 discriminator mapping 的支持。 OAS2-to-OAS3 converters 可以帮助迁移，但您必须手动更新映射。

在 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