OpenAPI能否为多态请求自动生成多个REST客户端方法？

核心结论 #

可以实现，但需要调整OpenAPI的注解配置和代码生成器参数，默认生成逻辑不会自动将oneOf结构拆分为多个重载方法。

具体调整步骤 #

1. 完善多态Schema注解 #

仅标注@Schema(oneOf = ...)不足以让生成器识别多态逻辑，需补充 discriminator（鉴别器）元数据：

• 在PayloadRequest接口上添加@Schema(discriminatorProperty = "requestType")，指定用于区分实现类的属性名。
• 在每个实现类上添加专属的discriminatorValue，明确类的识别标识。

调整后的代码示例：

@Schema(discriminatorProperty = "requestType")
public interface PayloadRequest {}

@Schema(discriminatorValue = "FLAT_FILE")
public class FlatFileRequest implements PayloadRequest {
    // 类属性定义
}

@Schema(discriminatorValue = "WEB_SERVICE")
public class WebServiceRequest implements PayloadRequest {
    // 类属性定义
}

@PostMapping("/new_test-endpoint")
public ResponseEntity<String> newTestEndpoint(@RequestBody
                                              @Schema(oneOf = {FlatFileRequest.class, WebServiceRequest.class})
                                              PayloadRequest payload);

2. 配置代码生成器启用多态与重载 #

在Maven或Gradle的OpenAPI生成器插件中，添加关键配置开启多态支持和方法重载生成：

Maven插件配置示例

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>6.6.0</version> <!-- 需使用适配OpenAPI 3.0.1的新版本 -->
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/openapi.yaml</inputSpec>
                <generatorName>java</generatorName>
                <configOptions>
                    <interfaceOnly>true</interfaceOnly>
                    <enablePolymorphism>true</enablePolymorphism>
                    <useOneOfInterfaces>true</useOneOfInterfaces> <!-- 核心配置：生成oneOf对应的重载方法 -->
                    <useBeanValidation>true</useBeanValidation>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

Gradle插件配置示例

plugins {
    id "org.openapi.generator" version "6.6.0"
}

openApiGenerate {
    generatorName = "java"
    inputSpec = "$rootDir/src/main/resources/openapi.yaml".toString()
    configOptions = [
        interfaceOnly: "true",
        enablePolymorphism: "true",
        useOneOfInterfaces: "true",
        useBeanValidation: "true"
    ]
}

3. 确认OpenAPI规范的正确性 #

如果通过SpringDoc自动生成OpenAPI规范，需确保最终的yaml/json文件包含完整的oneOf和discriminator配置，示例片段如下：

paths:
  /new_test-endpoint:
    post:
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/FlatFileRequest'
                - $ref: '#/components/schemas/WebServiceRequest'
              discriminator:
                propertyName: requestType
                mapping:
                  FLAT_FILE: '#/components/schemas/FlatFileRequest'
                  WEB_SERVICE: '#/components/schemas/WebServiceRequest'

验证生成结果 #

完成上述配置后重新生成客户端，即可得到期望的两个重载方法：

public String newTestEndpoint(FlatFileRequestDTO payload);

public String newTestEndpoint(WebServiceRequestDTO payload);

注意事项 #

• 生成器版本需不低于6.0.0，旧版本对oneOf的重载支持不完善；
• 所有实现类必须包含discriminatorProperty指定的属性（如requestType），否则序列化/反序列化时无法正确识别类型。

内容的提问来源于stack exchange，提问作者Diego Fernando Garcia Restrepo