Spring Boot 2.7.14中OpenAPI /api-docs返回JWT字符串而非JSON问题求助

排查方向1：确认SpringDoc依赖版本匹配 #

Spring Boot 2.7.x对应的SpringDoc OpenAPI稳定版本是1.6.x，版本不匹配可能导致响应格式异常。检查你的依赖配置：

<!-- Maven -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.15</version>
</dependency>

// Gradle
implementation 'org.springdoc:springdoc-openapi-ui:1.6.15'

排查方向2：检查全局消息转换器优先级 #

如果项目中自定义了HttpMessageConverter（比如StringHttpMessageConverter）并设置了高优先级，会导致Spring将OpenAPI的JSON响应强制转换为字符串输出。

解决方法： #

调整转换器优先级，确保MappingJackson2HttpMessageConverter优先处理JSON响应，同时避免干扰OpenAPI路径：

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    @Override
    public void extendMessageConverters(List<HttpMessageConverter<?>> converters) {
        // 将JSON转换器移到最前面，确保优先处理
        for (int i = converters.size() - 1; i >= 0; i--) {
            if (converters.get(i) instanceof MappingJackson2HttpMessageConverter) {
                converters.add(0, converters.remove(i));
                break;
            }
        }
        // 限制字符串转换器仅处理纯文本类型
        StringHttpMessageConverter stringConverter = new StringHttpMessageConverter();
        stringConverter.setSupportedMediaTypes(Collections.singletonList(MediaType.TEXT_PLAIN));
        converters.add(stringConverter);
    }
}

排查方向3：检查Spring Security拦截规则 #

即使未自定义过滤器，Spring Security集成JWT时可能默认拦截了/api-docs路径，导致JWT解析逻辑覆盖了OpenAPI的响应。

解决方法： #

在Security配置类中放行所有OpenAPI相关路径：

@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.authorizeRequests()
                .antMatchers("/api-docs/**", "/swagger-ui/**", "/swagger-ui.html")
                .permitAll()
                .anyRequest()
                .authenticated();
        // 若有自定义JWT过滤器，需确保这些路径不经过该过滤器
    }
}

排查方向4：检查全局ResponseBodyAdvice #

如果项目中存在@ControllerAdvice实现的ResponseBodyAdvice，可能无意中修改了/api-docs的响应内容，将JSON转为JWT字符串。

解决方法： #

在supports方法中排除OpenAPI路径，不处理其响应：

@ControllerAdvice
public class GlobalResponseBodyAdvice implements ResponseBodyAdvice<Object> {
    @Override
    public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {
        ServletRequestAttributes attributes = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
        if (attributes != null) {
            String uri = attributes.getRequest().getRequestURI();
            if (uri.startsWith("/api-docs")) {
                return false;
            }
        }
        return true;
    }

    @Override
    public Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType, Class<? extends HttpMessageConverter<?>> selectedConverterType, ServerHttpRequest request, ServerHttpResponse response) {
        // 原有逻辑保持不变
        return body;
    }
}

排查方向5：验证请求头Accept设置 #

如果请求的Accept头被设置为text/plain，Spring会返回字符串格式而非JSON。用curl测试：

curl -H "Accept: application/json" http://localhost:8080/api-docs

若测试正常，说明是Swagger UI的请求头配置问题，可通过自定义配置强制设置Accept头：

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("API文档").version("v1"));
    }

    @Bean
    public SwaggerUiConfigParameters swaggerUiConfigParameters() {
        SwaggerUiConfigParameters params = new SwaggerUiConfigParameters();
        params.addRequestHeader(new Header("Accept", "application/json"));
        return params;
    }
}

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