如何在Spring的OpenApi(swagger)中使用@RequestParam生成混合类型

前置依赖 #

首先确保你使用的是springdoc-openapi相关依赖（已停止维护的SpringFox对oneOf支持度极差，不推荐使用），根据SpringBoot版本选择对应版本即可：

• SpringBoot 2.x 使用1.x版本的springdoc-openapi
• SpringBoot 3.x 使用2.x版本的springdoc-openapi

实现代码 #

直接在@RequestParam标注的参数上添加@Parameter注解，通过schema的oneOf属性指定支持的类型即可，示例如下：

import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Schema;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class DemoController {

    @GetMapping("/demo")
    public void demoInterface(
        @Parameter(
            description = "支持字符串或整数类型的混合参数",
            schema = @Schema(oneOf = {String.class, Integer.class})
        )
        @RequestParam Object mixedParam
    ) {
        // 业务层自行判断参数类型处理
        if (mixedParam instanceof String strVal) {
            // 处理字符串类型逻辑
        } else if (mixedParam instanceof Integer intVal) {
            // 处理整数类型逻辑
        }
    }
}

生成效果 #

上述配置生成的OpenAPI定义会自动包含你需要的结构：

oneOf:
 - type: string
 - type: integer

注意事项 #

• 接收参数的类型必须声明为Object，否则Spring MVC的参数绑定转换器会在请求进入业务层前就做类型校验，不符合类型的请求会直接抛出参数错误
• 你可以在@Schema注解中额外添加pattern、minimum、maximum等属性，分别对字符串和整数的取值范围做限制
• 若你仍在使用已停更的SpringFox，无法直接通过注解实现该效果，需要自定义OpenAPI参数构造插件，实现成本极高，建议迁移到SpringDoc

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