Swagger2 非全局、无需重复输入的Head参数（Token）配置

最新推荐文章于 2026-06-27 13:13:33 发布

原创

最新推荐文章于 2026-06-27 13:13:33 发布 · 583 阅读

本文介绍了如何使用Swagger2配置非全局Header参数，避免重复输入Token。通过securitySchemes定义全局Header参数，然后在securityContexts中使用正则表达式排除特定接口。设置完成后，SwaggerUI的'Authorization'按钮用于输入参数，一次输入全局有效，提高接口调用效率。

优化方案如下：

通过Swagger2的securitySchemes配置全局参数：如下列代码所示，securitySchemes的ApiKey中增加一个名为“Authorization”，type为“header”的参数。

private List<ApiKey> securitySchemes() {
   
   
        return newArrayList(
                new ApiKey("Authorization", "Authorization", "header"));
 }

在Swagger2的securityContexts中通过正则表达式，设置需要使用参数的接口（或者说，是去除掉不需要使用参数的接口），如下列代码所示，通过PathSelectors.regex("^(?!auth).*$")，所有包含"auth"的接口不需要使用securitySchemes。即不需要使用上文中设置的名为“Authorization”，type为“header”的参数。

private List<SecurityContext> securityContexts() {
   
   
        return newArrayList(
                SecurityContext.builder()
                        .securityReferences(defaultAuth())
                        .forPaths(PathSelectors.regex("^(?!auth).*$"))
                        .build()
        );
    }

设置完成后进入SwaggerUI，右上角出现“Authorization”按钮，点击即可输入我们配置的参数。
对于不需要输入参数的接口（上文所述的包含auth的接口），在未输入Authorization参数就可以访问。
其他接口则将返回401错误。点击右上角“Authorization”按钮，输入配置的参数后即可访问。参数输入后全局有效，无需每个接口单独输入。

在这里插入图片描述

Swagger2的相关完整代码如下（工程基于Springboot）：

@Configuration
@EnableSwagger2
public class Swagger {
   
   
    @Bean
    public Docket api() {
   
   
        return new Docket(DocumentationType.SWAGGER_2).
                useDefaultResponseMessages(false)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.regex("^(?!auth).*$"))
                .build()
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts())
                ;
    }
 
    private List<ApiKey> securitySchemes()