作者简介:大家好,我是撸代码的羊驼,前阿里巴巴架构师,现某互联网公司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
@EnableSwagger2
public 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
@EnableSwagger2
public 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)));
}
}
此时重点是配置了Docket的securityContexts,通过该配置,设置了一个全局的变量“global”。注意defaultAuth方法中SecurityReference的第一个参数为你使用的token的key,我这里使用token。
此种方案展示效果如下:
在右上角会出现一个Authorize的选项。
点击“Authorize”,弹出下图。
在图中value的地方填写对应的token值,点击个Authorize。随后使用任何接口时都会在header部分添加对应token值。
小结
当然上述是以token为例进行讲解的,如果你想通过header传输其他参数,也可以借鉴此方法。在此实例中大家切勿全部copy,在具体场景下需要修改对应的参数值来进行使用。