Spring Boot微服务Swagger接口文档返回JWT而非JSON问题求助

基于Spring Boot 3.3.2的微服务部署在Kubernetes上，通过KONG API网关暴露，已集成springdoc-openapi-starter-webmvc-ui 2.6.0。配置完成后出现以下问题：

• 访问https://api.dev.cslpay.io/fx-rate-api/v3/api-docs/public时，返回JWT Token而非JSON格式的接口文档
• Swagger UI页面加载失败

相关配置如下：

POM依赖 #

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.6.0</version>
</dependency>

WebConverterConfig.java #

@EnableWebMvc
@Configuration
public class WebConverterConfig implements WebMvcConfigurer {

    @Override
    public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
        StringHttpMessageConverter messageConverter = new StringHttpMessageConverter();
        messageConverter.setSupportedMediaTypes(List.of(MediaType.APPLICATION_JSON, MediaType.TEXT_PLAIN, MediaType.ALL));
        converters.add(messageConverter);
        converters.add(new MappingJackson2HttpMessageConverter(new ObjectMapper()));
    }
}

SecurityConfig.java #

@EnableWebSecurity
@Configuration
@RequiredArgsConstructor
public class SecurityConfig {
    @Bean
    SecurityFilterChain filterChain(HttpSecurity http, CustomAuthenticationEntryPoint customAuthenticationEntryPoint, CustomAccessDenied customAccessDenied) throws Exception {
        return http.cors(cors -> cors.configurationSource(request -> {
                    CorsConfiguration configuration = new CorsConfiguration();
                    configuration.setAllowedOrigins(List.of("*"));
                    configuration.setAllowedMethods(List.of("*"));
                    configuration.setAllowedHeaders(List.of("*"));
                    return configuration;
                }))
                .csrf(AbstractHttpConfigurer::disable)
                .authorizeHttpRequests(auth -> {
                    auth.requestMatchers("/api/v1/auth/**", "/fx-rate-api/v3/api-docs/**", "/fx-rate-api/swagger-ui/**").permitAll();
                });
    }
}

SwaggerConfig.java #

@Configuration
public class SwaggerConfiguration {
    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .group("public")
                .pathsToMatch("/**")
                .build();
    }

    @Bean
    public OpenAPI usersMicroserviceOpenAPI() {
        final String securitySchemeName = "bearerAuth";
        final String securityDomainName = "Bearer";
        return new OpenAPI()
                .openapi("3.0.1")
                .addSecurityItem(new SecurityRequirement()
                        .addList(securitySchemeName)
                        .addList(securityDomainName)
                )
                .components(
                        new Components()
                                .addSecuritySchemes(securitySchemeName,
                                        new SecurityScheme()
                                                .name(securitySchemeName)
                                                .type(SecurityScheme.Type.HTTP)
                                                .scheme("bearer")
                                                .bearerFormat("JWT")
                                )
                );
    }
}

application.properties #

springdoc.api-docs.path=/fx-rate-api/v3/api-docs
springdoc.swagger-ui.path=/fx-rate-api/swagger-ui.html

1. 修复HttpMessageConverter顺序与媒体类型配置 #

WebConverterConfig中把StringHttpMessageConverter放在Jackson转换器前面，且配置了支持APPLICATION_JSON，导致Spring优先用字符串转换器处理JSON响应，破坏了swagger接口文档的格式输出。修改如下：

@EnableWebMvc
@Configuration
public class WebConverterConfig implements WebMvcConfigurer {

    @Override
    public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
        // 优先添加Jackson转换器处理JSON格式响应
        converters.add(new MappingJackson2HttpMessageConverter(new ObjectMapper()));
        
        // String转换器仅处理纯文本类型，避免干扰JSON解析
        StringHttpMessageConverter messageConverter = new StringHttpMessageConverter();
        messageConverter.setSupportedMediaTypes(List.of(MediaType.TEXT_PLAIN, MediaType.TEXT_HTML));
        converters.add(messageConverter);
    }
}

2. 修正Swagger认证配置错误 #

SwaggerConfig中SecurityRequirement添加了未定义的Bearer安全方案，导致Swagger UI加载时出现配置错误。移除无效的安全方案配置：

@Configuration
public class SwaggerConfiguration {
    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .group("public")
                .pathsToMatch("/**")
                .build();
    }

    @Bean
    public OpenAPI usersMicroserviceOpenAPI() {
        final String securitySchemeName = "bearerAuth";
        return new OpenAPI()
                .openapi("3.0.1")
                .addSecurityItem(new SecurityRequirement().addList(securitySchemeName))
                .components(
                        new Components()
                                .addSecuritySchemes(securitySchemeName,
                                        new SecurityScheme()
                                                .name(securitySchemeName)
                                                .type(SecurityScheme.Type.HTTP)
                                                .scheme("bearer")
                                                .bearerFormat("JWT")
                                )
                );
    }
}

3. 检查KONG网关路由配置 #

确保KONG网关未将/fx-rate-api/v3/api-docs/**和/fx-rate-api/swagger-ui/**路径纳入JWT认证拦截范围。在KONG控制台或配置文件中，将这些路径添加到匿名访问白名单，避免网关提前触发认证流程返回JWT Token。

4. 验证Security异常处理器逻辑 #

检查CustomAuthenticationEntryPoint和CustomAccessDenied的实现，确保它们不会错误拦截已配置permitAll的swagger相关路径。如果这两个类有全局生效的逻辑，需添加判断，跳过swagger路径的异常处理。

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