使用openapi-generator-maven-plugin生成Java代码遇编译语法错误

问题背景 #

使用openapi-generator-maven-plugin（版本6.6.0）从OpenAPI YAML文件生成Java代码，生成的代码存在语法错误，导致Maven编译失败。

Maven配置 #

<build>
    <plugins>
        <plugin>
            <groupId>org.openapitools</groupId>
            <artifactId>openapi-generator-maven-plugin</artifactId>
            <!-- RELEASE_VERSION -->
            <version>6.6.0</version>
            <!-- /RELEASE_VERSION -->
            <executions>
                <execution>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                    <configuration>
                        <inputSpec>${project.basedir}/src/main/resources/member_registration.yaml</inputSpec>
                        <generatorName>java</generatorName>
                        <skipValidateSpec>true</skipValidateSpec>
                        <configOptions>
                            <sourceFolder>src/gen/java/main</sourceFolder>
                            <useTags>true</useTags>
                        </configOptions>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

编译错误日志 #

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.8.1:compile (default-compile) on project swagger-to-code: Compilation failure: Compilation failure:
[ERROR] /C:/My Data/workspace/poc/swagger-to-code-poc/swagger-to-code/target/generated-sources/openapi/src/gen/java/main/org/openapitools/client/model/SearchUsersByUsername200Response.java:[75,35] > expected
[ERROR] /C:/My Data/workspace/poc/swagger-to-code-poc/swagger-to-code/target/generated-sources/openapi/src/gen/java/main/org/openapitools/client/model/SearchUsersByUsername200Response.java:[75,36] not a statement
[ERROR] /C:/My Data/workspace/poc/swagger-to-code-poc/swagger-to-code/target/generated-sources/openapi/src/gen/java/main/org/openapitools/client/model/SearchUsersByUsername200Response.java:[75,58] not a statement
[ERROR] /C:/My Data/workspace/poc/swagger-to-code-poc/swagger-to-code/target/generated-sources/openapi/src/gen/java/main/org/openapitools/client/model/SearchUsersByUsername200Response.java:[75,62] illegal start of expression
[ERROR] /C:/My Data/workspace/poc/swagger-to-code-poc/swagger-to-code/target/generated-sources/openapi/src/gen/java/main/org/openapitools/client/model/SearchUsersByUsername200Response.java:[75,75] not a statement

有问题的生成代码片段 #

public void write(JsonWriter out, SearchUsersByUsername200Response value) throws IOException {
    if (value == null || value.getActualInstance() == null) {
        elementAdapter.write(out, null);
        return;
    }

    // check if the actual instance is of the type `List<UserSummaryExtended>`
    if (value.getActualInstance() instanceof List<UserSummaryExtended>) {
        JsonObject obj = adapterList<UserSummaryExtended>.toJsonTree((List<UserSummaryExtended>)value.getActualInstance()).getAsJsonObject();
        elementAdapter.write(out, obj);
        return;
    }
}

问题分析与解决方案 #

问题原因 #

生成代码中出现了HTML转义字符<（对应<）和>（对应>），而Java语法要求泛型使用<>，这些转义字符直接导致编译报错。

解决步骤 #

1. 修复OpenAPI YAML文件
   检查YAML中SearchUsersByUsername200Response对应的schema定义，确保泛型类型未使用HTML转义字符。例如，将<List<UserSummaryExtended>>替换为标准的List<UserSummaryExtended>格式。

2. 启用Spec验证
   将Maven配置中的<skipValidateSpec>true</skipValidateSpec>改为<skipValidateSpec>false</skipValidateSpec>，让插件自动检测并提示YAML文件中的格式问题，提前修复潜在错误。

3. 升级插件版本
   6.6.0版本存在HTML转义处理的bug，建议升级到最新稳定版（如7.x系列），此类转义问题在后续版本中已被官方修复。

4. 临时应急修复
   如果暂时无法修改YAML或升级插件，可手动替换生成代码中所有的<为<、>为>，但此方法需要每次生成代码后重复操作，仅作为临时过渡方案。

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