Spring Boot 3.2集成Swagger版本字段无效错误的解决方法

这个错误的核心原因是自定义的HttpMessageConverter替换了默认转换器，导致SpringDoc生成的OpenAPI文档无法正确序列化出version字段，结合你的代码配置，按以下步骤修复：

1. 修正WebMvcConfig的转换器配置 #

你当前使用configureMessageConverters方法会清空所有默认的HttpMessageConverter，这会破坏SpringDoc依赖的序列化逻辑。改成使用extendMessageConverters方法，只添加自定义转换器而不替换默认的：

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

    @Override
    public void extendMessageConverters(List<HttpMessageConverter<?>> converters) {
        Jackson2ObjectMapperBuilder builder = new Jackson2ObjectMapperBuilder();
        builder.serializerByType(ObjectId.class, new ToStringSerializer());

        MappingJackson2HttpMessageConverter converter = new MappingJackson2HttpMessageConverter(builder.build());
        // 将自定义转换器放到最前面，保证优先使用
        converters.add(0, converter);
    }
}

如果必须使用configureMessageConverters，则需要保留Spring默认的转换器，不要直接清空后只加自己的，正确写法是：

@Override
public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
    // 先添加默认转换器
    WebMvcConfigurer.super.configureMessageConverters(converters);
    
    // 再添加自定义转换器
    Jackson2ObjectMapperBuilder builder = new Jackson2ObjectMapperBuilder();
    builder.serializerByType(ObjectId.class, new ToStringSerializer());

    MappingJackson2HttpMessageConverter converter = new MappingJackson2HttpMessageConverter(builder.build());
    converters.add(0, converter);
}

2. 确认SpringDoc版本与Spring Boot兼容 #

Spring Boot 3.2对应的springdoc-openapi-starter-webmvc-ui最低版本是2.2.0，你使用的2.3.0是兼容的，无需修改依赖版本，但如果后续仍有问题，可以尝试升级到最新稳定版。

3. 验证OpenAPI版本配置 #

你的配置中springdoc.api-docs.version=openapi_3_1是符合Spring Boot 3.2要求的（Spring Boot 3.x默认支持OpenAPI 3.1），无需调整，但确保配置文件格式正确（比如是application.yml而非application.properties）。

完成以上修改后，重启服务访问swagger-ui，错误应该会消失。

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