SpringBoot集成swagger2配置权限认证参数

news2025/11/30 15:48:12

作者简介：大家好，我是撸代码的羊驼，前阿里巴巴架构师，现某互联网公司CTO

联系v：sulny_ann（17362204968），加我进群，大家一起学习，一起进步，一起对抗互联网寒冬

在使用swagger2时，如果api接口需要token等权限认证内容，那么此时可以有两种方案进行解决：方案一，每个请求上面都添加对应token的key和value值。方案二：全局统一添加权限认证的token。

一般情况下token都存放在header中。

引入swagger2依赖

引入对应的swagger2依赖：

<dependency>    <groupId>io.springfox</groupId>    <artifactId>springfox-swagger2</artifactId>    <version>2.9.2</version></dependency><dependency>    <groupId>io.springfox</groupId>    <artifactId>springfox-swagger-ui</artifactId>    <version>2.9.2</version></dependency>

集成配置方案一

首先我们来看第一种方案，也就是每个请求都添加对应header信息，对应的config文件配置如下：

import com.google.common.collect.Lists;import io.swagger.annotations.ApiOperation;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import springfox.documentation.builders.ApiInfoBuilder;import springfox.documentation.builders.ParameterBuilder;import springfox.documentation.builders.PathSelectors;import springfox.documentation.builders.RequestHandlerSelectors;import springfox.documentation.schema.ModelRef;import springfox.documentation.service.*;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spi.service.contexts.SecurityContext;import springfox.documentation.spring.web.plugins.Docket;import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;import java.util.Collections;import java.util.List;
import static com.google.common.collect.Lists.newArrayList;
@Configuration@EnableSwagger2public class SwaggerConfig {  @Bean  public Docket createRestApi() {    ParameterBuilder parameterBuilder = new ParameterBuilder();    List<Parameter> parameters = Lists.newArrayList();    parameterBuilder        .name("token")        .description("token令牌")        .modelRef(new ModelRef("String"))        .parameterType("header")        .defaultValue("")        .required(false).build();    parameters.add(parameterBuilder.build());
    return new Docket(DocumentationType.SWAGGER_2)        .apiInfo(apiInfo())        .select()        //加了ApiOperation注解的类，才生成接口文档        .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))        //包下的类，才生成接口文档        .apis(RequestHandlerSelectors.basePackage("com.chengdeshi.controller"))        .paths(PathSelectors.any())        .build()        .globalOperationParameters(parameters)        .securitySchemes(security());  }
  private ApiInfo apiInfo() {    return new ApiInfoBuilder()        .title("文档")        .description("文档")        .termsOfServiceUrl("https://www.choupangxia.com")        .version("4.0.0")        .build();  }
  private List<ApiKey> security() {    return newArrayList(        new ApiKey("token", "token", "header")    );  }
}

重点是构建了ParameterBuilder对象，并通过globalOperationParameters将其配置到Docket中。

此时展示效果如下：

执行每个接口请求时都需要添加token值，除非写死默认值。

集成配置方案二

如果不想每次都填写这么一个token字段，每次都手动进行填写。那么可以通过统一全局配置。

对应的配置文件配置如下：

import io.swagger.annotations.ApiOperation;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 springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;import java.util.Collections;import java.util.List;
import static com.google.common.collect.Lists.newArrayList;
@Configuration@EnableSwagger2public class SwaggerConfig {  @Bean  public Docket createRestApi() {    return new Docket(DocumentationType.SWAGGER_2)        .apiInfo(apiInfo())        .select()        //加了ApiOperation注解的类，才生成接口文档        .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))        //包下的类，才生成接口文档        .apis(RequestHandlerSelectors.basePackage("com.chengdeshi.controller"))        .paths(PathSelectors.any())        .build()        .securityContexts(securityContexts())        .securitySchemes(security());  }
  private ApiInfo apiInfo() {    return new ApiInfoBuilder()        .title("文档")        .description("文档")        .termsOfServiceUrl("https://www.choupangxia.com")        .version("4.0.0")        .build();  }
  private List<ApiKey> security() {    return newArrayList(        new ApiKey("token", "token", "header")    );  }
  private List<SecurityContext> securityContexts() {    return new ArrayList(        Collections.singleton(SecurityContext.builder()            .securityReferences(defaultAuth())            .forPaths(PathSelectors.regex("^(?!api).*$"))            .build())    );  }
  List<SecurityReference> defaultAuth() {    AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");    AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];    authorizationScopes[0] = authorizationScope;    return new ArrayList(        Collections.singleton(new SecurityReference("token", authorizationScopes)));  }
}