Swagger2添加JWT授权配置后报v2/apidocs undefined错误求助

• 核心配置错误：defaultAuth()方法存在逻辑bug。你声明了长度为1的AuthorizationScope数组，但未将提前创建的global权限作用域对象存入数组，最终传入SecurityReference的是持有null元素的空数组。Springfox在生成/v2/api-docs接口返回内容时会触发空指针，导致序列化失败，前端Swagger UI拉取不到合法的文档结构，就会抛出Fetch error v2/apidocs undefined错误。
• 权限放行规则不全：当前Spring Security仅配置了4条Swagger相关路径放行，遗漏了swagger资源集合、安全配置项、静态webjar资源等路径，即使修复核心代码问题，后续也可能出现资源加载403的异常。

1. 修正Swagger JWT配置的数组赋值错误 #

将defaultAuth()方法修改为如下内容，补全缺失的数组赋值逻辑：

private List<SecurityReference> defaultAuth(){
    AuthorizationScope authorizationScope = new AuthorizationScope("global","accessEverything");
    AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
    // 补全数组赋值
    authorizationScopes[0] = authorizationScope;
    return Arrays.asList(new SecurityReference("JWT", authorizationScopes));
}

修正后完整的Swagger配置参考：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiDetails())
                .securityContexts(Arrays.asList(securityContext()))
                .securitySchemes(Arrays.asList(apiKey()))
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
    
    private ApiInfo apiDetails() {
        return new ApiInfoBuilder()
                .title("smartportal API")
                .description("smartportal API documentation")
                .version("2.0.1")
                .build();
    }
    
    private ApiKey apiKey() {
        return new ApiKey("JWT","Authorization","header");
    }
    
    private SecurityContext securityContext() {
        return SecurityContext.builder().securityReferences(defaultAuth()).build();
    }

    private List<SecurityReference> defaultAuth(){
        AuthorizationScope authorizationScope = new AuthorizationScope("global","accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        return Arrays.asList(new SecurityReference("JWT", authorizationScopes));
    }
}

2. 补全Spring Security的Swagger路径放行规则 #

将原有放行配置替换为如下完整配置，覆盖所有Swagger运行所需的资源路径：

.antMatchers(
    "/v2/api-docs/**",
    "/v2/api-docs",
    "/swagger-resources/**",
    "/swagger-resources/configuration/ui",
    "/swagger-resources/configuration/security",
    "/swagger-ui/**",
    "/swagger-ui/index.html",
    "/webjars/**"
).permitAll()

3. 异常排查（上述两步操作后仍报错时检查） #

• 检查项目自定义的全局拦截器、过滤器，确认其未拦截/v2/api-docs路径
• 检查是否配置了全局响应体包装处理器，若有需要排除/v2/api-docs路径，避免返回的JSON文档结构被修改导致Swagger UI无法解析
• 重启服务后先直接访问http://服务地址/v2/api-docs，确认接口能正常返回JSON格式的接口文档内容，再访问Swagger UI页面即可看到Authorize按钮正常显示。

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