Spring 2.7.12+Spring Security OAuth2下OpenAPI3 api-docs返回加密JWT

问题背景 #

已将Spring Boot版本升级至2.7.12，从SpringFox Swagger 2迁移到springdoc-openapi 3（Swagger 3）。Swagger UI能正常访问，但/v3/api-docs接口的响应被加密成JWT令牌，导致Swagger UI无法解析接口文档。尝试过以下方案但未解决：

• 在WebMvcConfig中忽略Swagger相关URL
• 添加Swagger资源处理器
• 自定义StringHttpMessageConverter和ByteArrayHttpMessageConverter

问题根源 #

你的WebMvcConfig中注册了全局生效的requestInterceptor，该拦截器会对所有请求的响应进行JWT加密处理，包括springdoc提供的/v3/api-docs接口。WebSecurity的忽略配置仅针对安全拦截，不会影响WebMvc层面的拦截器。

解决方案 #

在注册拦截器时，排除Swagger相关的接口路径，让这些接口的响应不被加密处理。修改WebMvcConfig中的addInterceptors方法：

@Override
public void addInterceptors(InterceptorRegistry registry) {
    registry.addInterceptor(requestInterceptor)
            // 排除springdoc相关路径
            .excludePathPatterns(
                "/v3/api-docs/**",
                "/swagger-ui/**",
                "/swagger-ui.html",
                "/webjars/**"
            );
}

额外验证点 #

1. 确认springdoc的默认接口路径：springdoc-openapi 3的默认API文档路径是/v3/api-docs，如果你的配置中修改过路径，需要同步添加到排除列表
2. 检查requestInterceptor的逻辑，确保它只对业务接口进行加密，而非全局所有接口
3. 验证Swagger资源路径是否正确：你的资源处理器配置已经覆盖了/swagger-ui/**和/webjars/**，无需修改

相关配置参考（已修正拦截器部分） #

WebMvcConfig 修正后代码 #

@Configuration
@EnableWebMvc
public class WebMvcConfig implements WebMvcConfigurer {

  @Autowired
  private RequestInterceptor requestInterceptor;

  @Value("${allowed.headers}")
  private String allowedHeaders;

  @Override
  public void configureMessageConverters(@NotNull List<HttpMessageConverter<?>> converters) {
    WebMvcConfigurer.super.configureMessageConverters(converters);
    converters.add(0, new MappingJackson2HttpMessageConverter(provideObjectMapper()));
    converters.add(new ByteArrayHttpMessageConverter());
    converters.add(new StringHttpMessageConverter());
  }

  @Bean
  public ObjectMapper provideObjectMapper() {
    return new ObjectMapper()
        .setDefaultPropertyInclusion(JsonInclude.Include.NON_NULL)
        .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES);
  }

  @Override
  public void addCorsMappings(CorsRegistry registry) {
    registry.addMapping("/**").exposedHeaders(Constants.AUTHORIZATION_TOKEN)
            .allowedHeaders(allowedHeaders.split(","));
  }

  @Override
  public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("/swagger-ui/**")
        .addResourceLocations("classpath:/META-INF/resources/");
    registry.addResourceHandler("/webjars/**")
        .addResourceLocations("classpath:/META-INF/resources/webjars/");
  }

  @Override
  public void addArgumentResolvers(List<HandlerMethodArgumentResolver> argumentResolvers) {
    argumentResolvers.add(new PageableHandlerMethodArgumentResolver());
  }

  @Override
  public void addInterceptors(InterceptorRegistry registry) {
    registry.addInterceptor(requestInterceptor)
            .excludePathPatterns(
                "/v3/api-docs/**",
                "/swagger-ui/**",
                "/swagger-ui.html",
                "/webjars/**"
            );
  }

}

其他配置保持不变 #

WebSecurityConfiguration和OpenApiConfig的配置无需修改，依赖配置也保持现有版本即可。

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