Springdoc OpenAPI中@RouterOperation的@Parameter内@Schema(type="integer")失效问题

问题描述 #

使用Spring WebFlux + Springdoc OpenAPI 2.5.0，通过@RouterOperation配置API文档时，@Parameter中指定的schema = @Schema(type = "integer")未生效，Swagger UI里id参数仍显示为字符串或未应用指定类型。相关代码如下：

@RouterOperation(
path = "/api/hello",
operation = @Operation(
    security = @SecurityRequirement(name = UtilitiesConstant.OpenApiSecurityName),
    summary = "Get User by ID",
    description = "Fetch a user by their ID",
    operationId = "getHello",
    parameters = {
        @Parameter(
            name = "id",
            in = ParameterIn.QUERY,
            description = "User ID",
            required = true,
            schema = @Schema(type = "integer")
        )
    },
    responses = {
        @ApiResponse(responseCode = "200", description = "Successful operation"),
        @ApiResponse(responseCode = "404", description = "User not found")
    }
)

已开启logging.level.org.springdoc=DEBUG日志，但未找到有效报错信息。

可能原因及解决建议 #

• 改用implementation指定类型：放弃手动设置type = "integer"，直接通过schema = @Schema(implementation = Integer.class)指定Java类型，Springdoc会基于类型元数据正确生成schema，避免字符串类型推断错误。
• 校验Spring Boot版本兼容性：Springdoc 2.5.0适配Spring Boot 3.x版本，如果你的项目用的是Spring Boot 2.x，会出现注解解析异常。确保版本匹配（Springdoc 1.x对应Spring Boot 2.x，2.x对应Spring Boot 3.x）。
• 检查路由函数参数类型：Springdoc处理函数式端点时，会优先从路由处理方法的参数类型推断schema。如果你的路由函数中id参数定义为String类型，注解配置会被覆盖，需确保参数类型为Integer。
• 升级Springdoc版本：Springdoc 2.5.0存在函数式端点注解解析的已知Bug，升级到2.6.0及以上版本可修复该类问题。
• 排查注解冲突：检查是否在路由函数或其他地方重复配置了@Parameter，导致手动指定的schema被覆盖。

内容的提问来源于stack exchange，提问作者Minh Trần