Spring Boot 3.4.5集成Swagger UI报错：无法渲染定义（版本字段无效）

近期将Spring Boot版本升级至3.4.5，本地Swagger接口验证功能正常，但UI界面提示错误：Unable to render definition: Please indicate valid Swagger or OpenAPI version field.

当前依赖版本 #

• io.swagger.core.v3:swagger-annotations-jakarta:jar:2.2.25
• io.swagger.core.v3:swagger-core:2.2.25
• io.swagger.core.v3:swagger-models:2.2.25
• org.springdoc:springdoc-openapi-starter-common:2.2.25
• io.swagger.core.v3:swagger-annotations-jakarta:jar:2.2.25
• com.fasterxml.jackson.core -> 2.18.3 BOM
• springdoc-openapi-starter-common: 2.7.0
• springdoc-openapi-starter-webmvc-ui: 2.7.0
• springdoc-openapi-starter-webmvc-api: 2.7.0

application.yml配置 #

springdoc:
  default-produces-media-type: application/json
  swagger-ui:
    disable-swagger-default-url: true
    query-config-enabled: true
    path: /swagger-ui.html
  api-docs:
    path: /v3/api-docs
    version: openapi_3_0

自定义WebMvcConfigurer代码 #

@Override
public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
    converters.add(new StringHttpMessageConverter());
    converters.add(new ByteArrayHttpMessageConverter());
    converters.add(new MappingJackson2HttpMessageConverter(objectMapper()));
}

public ObjectMapper objectMapper() {
    val mapper = new ObjectMapper();
    mapper.setSerializationInclusion(JsonInclude.Include.ALWAYS);
    mapper.registerModule(new JsonNullableModule());
    mapper.registerModule(new JavaTimeModule());
    mapper.registerModule(new Jdk8Module());
    mapper.configure(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS, false);
    mapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
    return mapper;
}

POM依赖片段 #

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-common</artifactId>
    <version>2.7.0</version>
</dependency>
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.7.0</version>
</dependency>
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
    <version>2.7.0</version>
</dependency>

排查建议 #

1. 修复依赖版本冲突
   依赖列表中springdoc-openapi-starter-common存在2.2.25和2.7.0两个版本，这会导致核心组件版本不一致，引发文档生成异常。执行mvn dependency:tree查看依赖树，通过<exclusions>排除低版本的springdoc-openapi-starter-common依赖，确保所有springdoc组件使用统一的2.7.0版本。

2. 修正OpenAPI版本配置
   当前springdoc.api-docs.version配置值为小写的openapi_3_0，springdoc官方要求该配置值为大写枚举值OPENAPI_3_0。修改配置后，重新启动服务，检查/v3/api-docs返回的文档是否包含openapi: 3.0.x字段。

3. 排查自定义ObjectMapper影响
   自定义的ObjectMapper可能未正确序列化OpenAPI规范中的版本字段。尝试临时注释掉自定义的configureMessageConverters方法，使用Spring Boot默认的消息转换器，验证Swagger UI是否恢复正常。如果恢复，需为自定义ObjectMapper添加springdoc所需的Jackson模块支持，或调整序列化配置。

4. 验证OpenAPI文档完整性
   直接访问/v3/api-docs接口，查看返回的JSON结构中是否存在openapi字段。如果该字段缺失，说明springdoc未能正确生成符合规范的文档，需重点排查依赖冲突或配置问题；如果字段存在，尝试清除浏览器缓存、强制刷新页面或更换浏览器测试，排除前端缓存问题。

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