Spring库更新后Swagger-UI无法正常显示的问题

问题根源 #

升级springdoc-openapi到1.6.16及以上版本后，/v3/api-docs返回的是Gzip压缩后的内容，Swagger UI未配置自动解压，导致无法解析出合法的OpenAPI版本字段，从而触发报错。

解决方案 #

方案1：临时禁用Gzip压缩（快速验证） #

在配置文件（application.properties或application.yml）中添加以下配置，禁用全局压缩：

server.compression.enabled=false

重启应用后，访问/v3/api-docs应返回正常JSON，Swagger UI即可正常渲染。

方案2：配置Swagger UI支持压缩响应 #

若需保留Gzip压缩，可通过配置让Swagger UI发送Accept-Encoding请求头，并处理压缩响应：

方式一：配置文件方式

在application.properties中添加：

springdoc.swagger-ui.request-headers[0].name=Accept-Encoding
springdoc.swagger-ui.request-headers[0].value=gzip, deflate

方式二：Java配置类方式

创建SpringDoc配置类，注入请求头配置：

import org.springdoc.core.SwaggerUiConfigParameters;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpHeaders;

@Configuration
public class SpringDocConfiguration {
    @Bean
    public SwaggerUiConfigParameters swaggerUiConfigParameters() {
        SwaggerUiConfigParameters configParams = new SwaggerUiConfigParameters();
        configParams.addRequestHeader(new org.springdoc.core.models.HttpHeader(HttpHeaders.ACCEPT_ENCODING, "gzip, deflate"));
        return configParams;
    }
}

方案3：升级springdoc-openapi到兼容版本 #

尝试升级到适配Spring Boot 2.7.x的最新稳定版（如1.8.0），该版本已修复部分压缩相关的兼容性问题：

<!-- Maven依赖示例 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.8.0</version>
</dependency>

排查验证 #

用curl命令直接测试接口是否返回压缩内容：

# 请求接口并解压响应
curl -H "Accept-Encoding: gzip, deflate" http://localhost:8080/v3/api-docs | gunzip

若返回正常JSON，即可确认是Swagger UI未处理压缩响应的问题。

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