如何配置openapi-generator-maven-plugin将枚举映射为String类型？

问题背景 #

使用openapi-generator-maven-plugin生成第三方API客户端时，第三方服务器频繁修改字符串枚举值，导致生成的Java枚举类在枚举新增或重命名时引发生产故障。需要将所有枚举转为String类型，避免因枚举变更带来的回归风险。

可行配置方案 #

通过插件配置或OpenAPI规范扩展，可实现枚举到String类型的映射，有两种方式可选：

1. 全局禁用所有枚举生成（推荐） #

在插件的configOptions中添加<enumToString>true</enumToString>参数，所有OpenAPI中的字符串枚举都会被生成为Java的String类型，而非枚举类。

修改后的完整插件配置：

<configuration>
    <inputSpec>${project.basedir}/src/main/resources/third-party-api.json</inputSpec>
    <generatorName>java</generatorName>
    <library>webclient</library>
    <apiPackage>integrations.thirdparty.api</apiPackage>
    <invokerPackage>integrations.thirdparty.invoker</invokerPackage>
    <modelPackage>integrations.thirdparty.model</modelPackage>
    <output>${project.build.directory}/generated-sources/</output>
    <generateApiTests>false</generateApiTests>
    <generateModelTests>false</generateModelTests>
    <skipIfSpecIsUnchanged>true</skipIfSpecIsUnchanged>
    <skipValidateSpec>true</skipValidateSpec>
    <configOptions>
        <sourceFolder>.</sourceFolder>
        <enumToString>true</enumToString> <!-- 新增此配置项 -->
    </configOptions>
</configuration>

2. 针对特定枚举单独配置 #

若无需全局修改，可在OpenAPI规范的对应Schema中添加x-enum-to-string扩展属性，仅将该字段生成为String类型：

"type": {
  "type": "string",
  "enum": [
    "PARLAY",
    "STRAIGHT",
    "FUTURE",
    "TABLE",
    "SLOT"
  ],
  "x-enum-to-string": true
}

效果验证 #

配置生效后，原生成的LedgerEntryReasonEnum枚举类会被替换为POJO中的String类型字段：

private String type; // 原枚举字段转为String类型

后续第三方新增或修改枚举值时，客户端无需重新生成代码，也不会因枚举不匹配抛出反序列化异常。

内容的提问来源于stack exchange，提问作者IcedDante