如何让openapi-generator-maven-plugin支持两种响应媒体类型？

问题背景 #

使用openapi-generator-maven-plugin（版本5.4.0）结合Java生成器与WebClient库生成代码时，遇到一个端点返回两种响应类型：application/octet-stream（对应byte[]）和application/json（对应TheResponseObject），其OpenAPI定义如下：

"responses": {
  "200": {
    "content": {
      "application/octet-stream": {
        "schema": {
          "type": "string",
          "format": "byte"
        }
      },
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/TheResponseObject"
        }
      }
    }
  }
}

当前插件仅按声明顺序取第一个媒体类型生成返回类型：顺序不变时返回byte[]，调换顺序则返回TheResponseObject，无法根据响应头动态处理两种类型。

可行解决方案 #

1. 自定义生成模板 #

openapi-generator支持通过Mustache模板自定义生成逻辑，可修改WebClient相关模板实现动态响应处理：

• 复制插件默认的WebClient模板（如api.mustache）到项目的src/main/resources/openapi-generator/templates目录
• 修改模板中响应处理的代码块，添加Content-Type判断逻辑：先获取响应头的Content-Type，再根据类型解析为对应的数据结构
• 在Maven插件配置中指定自定义模板目录：

<plugin>
  <groupId>org.openapitools</groupId>
  <artifactId>openapi-generator-maven-plugin</artifactId>
  <version>5.4.0</version>
  <configuration>
    <templateDirectory>${project.basedir}/src/main/resources/openapi-generator/templates</templateDirectory>
    <!-- 其他原有配置 -->
  </configuration>
</plugin>

这种方式一劳永逸，后续重新生成代码会自动包含逻辑，但需要熟悉模板语法。

2. 手动扩展生成的API类 #

若不想修改模板，可在生成代码后手动扩展API类，新增支持双类型的方法：

• 保留插件生成的默认方法（仅处理单一类型）
• 添加自定义方法，使用WebClient的exchange()方法替代retrieve()，实现响应头检查与动态解析：

public Mono<Object> yourEndpointDualResponse(/* 原方法参数 */) {
    return webClient.get()
            .uri(/* 原URI构建逻辑 */)
            .exchangeToMono(response -> {
                String contentType = response.headers()
                        .contentType()
                        .map(MediaType::toString)
                        .orElse("");
                
                if (MediaType.APPLICATION_OCTET_STREAM_VALUE.equals(contentType)) {
                    return response.bodyToMono(byte[].class);
                } else if (MediaType.APPLICATION_JSON_VALUE.equals(contentType)) {
                    return response.bodyToMono(TheResponseObject.class);
                }
                return Mono.error(new RuntimeException("不支持的Content-Type: " + contentType));
            });
}

这种方式无需修改生成配置，但每次重新生成代码后需重新添加或合并该方法。

3. 调整OpenAPI契约（折中方案） #

若上述两种方式都不适用，可尝试修改OpenAPI定义：将两种响应拆分为不同的HTTP状态码，或定义一个包含两种类型字段的通用响应对象。但此方式需要调整API契约，可能不符合业务实际需求，仅作为备选。

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