Spring Boot中Swagger UI认证按钮不显示问题求解

一、使用SpringDoc OpenAPI（推荐，替代Springfox） #

如果你的项目适配Spring Boot 2.6+，优先用SpringDoc OpenAPI（原Springfox Swagger已停止维护），按以下步骤配置：

1. 添加依赖
   在pom.xml中引入SpringDoc的starter依赖：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.2.0</version> <!-- 可替换为最新稳定版 -->
</dependency>

2. 配置JWT认证规则
   创建OpenAPI配置类，定义全局安全认证方案，让Swagger UI显示认证按钮：

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                // 全局启用JWT认证要求
                .addSecurityItem(new SecurityRequirement().addList("bearerAuth"))
                .components(new Components()
                        // 定义JWT认证的格式和位置
                        .addSecuritySchemes("bearerAuth", new SecurityScheme()
                                .type(SecurityScheme.Type.HTTP)
                                .scheme("bearer")
                                .bearerFormat("JWT")
                                .in(SecurityScheme.In.HEADER)
                                .name("Authorization")));
    }
}

3. 验证效果
   启动Spring Boot应用，访问http://localhost:8080/swagger-ui/index.html，右上角会出现Authorize按钮。点击后输入Bearer {你的JWT令牌}（注意Bearer后加空格），即可带着认证令牌请求接口。

二、使用旧版Springfox Swagger2 #

如果项目仍依赖Springfox Swagger2，按以下配置：

1. 添加依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version> <!-- Springfox最后一个稳定版 -->
</dependency>

2. 配置Swagger2的JWT认证
   创建Swagger配置类：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ApiKey;
import springfox.documentation.service.AuthorizationScope;
import springfox.documentation.service.SecurityReference;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;

import java.util.List;

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .securityContexts(List.of(securityContext()))
                .securitySchemes(List.of(apiKey()))
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.yourproject.controller")) // 替换为你的Controller包路径
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API接口文档")
                .description("支持JWT认证的接口文档")
                .version("1.0")
                .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 List.of(new SecurityReference("JWT", authorizationScopes));
    }
}

3. 验证效果
   启动应用后访问http://localhost:8080/swagger-ui/，右上角会出现Authorize按钮，输入Bearer {你的JWT令牌}即可完成认证。

三、常见排查要点 #

• 检查依赖版本是否与Spring Boot版本兼容（比如Spring Boot 3.x只能用SpringDoc OpenAPI 2.x+）
• 确认配置类被Spring Boot扫描到（配置类所在包与主启动类包同层级，或添加了@ComponentScan指定扫描路径）
• 若接口添加了@PreAuthorize等权限注解，需确保Swagger配置中已绑定安全上下文
• 清除浏览器缓存或用隐身模式打开Swagger UI，避免缓存导致的显示异常

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