Spring Boot 3中Swagger生成实体Controller的ID类型异常问题求助

以下是几种可行的解决办法，按优先级推荐：

1. 给Controller参数显式指定Swagger类型 #

在接收ID的Controller方法参数上，通过@Parameter注解明确指定schema的类型和格式，强制Swagger将Long类型渲染为整数类型：

@GetMapping("/eval-periods/{id}")
public ResponseEntity<EvalPeriod> getEvalPeriod(
    @Parameter(schema = @Schema(type = "integer", format = "int64"))
    @PathVariable("id") Long id
) {
    // 业务逻辑实现
}

2. 全局配置Long类型的Swagger映射 #

创建SpringDoc配置类，全局修正Long类型在Swagger Schema中的映射规则，避免所有Long字段被默认转为String：

@Configuration
public class SpringDocConfig {
    @Bean
    public OpenApiCustomizer longTypeSchemaCustomizer() {
        return openApi -> {
            openApi.getComponents().getSchemas().values().forEach(schema -> {
                // 修正Long类型的Swagger schema定义
                if ("string".equals(schema.getType()) && "int64".equals(schema.getFormat())) {
                    schema.setType("integer");
                }
            });
        };
    }
}

3. 检查实体类与转换配置 #

• 确认实体类的ID字段注解正确，未被错误配置为String类型：

@Entity
public class EvalPeriod {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    @Column(name = "id", nullable = false)
    private Long id;

    // 其他字段、getter和setter
}

• 排查项目中是否存在自定义的Converter或Formatter，这些组件可能干扰了Long与String的默认转换逻辑，若有冲突需调整其优先级或排除对Long类型的处理。

问题原因说明 #

springdoc-openapi 2.0.0在Spring Boot 3环境下，部分场景会将Java的Long类型默认映射为String类型（可能与Jackson序列化配置或类型解析逻辑有关），导致Swagger文档中ID显示为String，而实际接口接收请求时，Spring尝试将传入的数字字符串转换为Long，但如果存在自定义转换组件冲突，就会触发ConverterNotFoundException错误。

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