swagger配置使用及安全方案
1.swagger的依赖
pom依赖,这是针对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>
pom依赖,这是针对swagger3的
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.2.31</version>
</dependency>
2.swagger配置
swagger2配置需要添加两个注解,包括@EnableSwagger2和@Configuration
此处需要留意,如果项目是基于springmvc,需要手动添加配置注册swagger,帮助mvc找到swagger-ui.html对应的文件
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
swagger3配置需要添加一个配置类
上图中涉及了三个子对象,起到的作用不同:
components主要是用于配置用户的token认证校验 Components对象里面包含Map<String, SecurityScheme>结构的securitySchemes对象
public OpenAPI components(Components components) {
this.components = components;
return this;
}
// 1.1.securitySchemes对象包含key和SecurityScheme对象,SecurityScheme对象里面包含type,name,in,description等参数字段
public Components addSecuritySchemes(String key, SecurityScheme securitySchemesItem) {
if (this.securitySchemes == null) {
this.securitySchemes = new LinkedHashMap();
}
this.securitySchemes.put(key, securitySchemesItem);
return this;
}
info主要用于swagger页面的标题和版本确认,Info对象包含title,version和description字段
public OpenAPI info(Info info) {
this.info = info;
return this;
}
externalDocs用于标题下面的链接,ExternalDocumentation内部又包含description和url字段
public OpenAPI externalDocs(ExternalDocumentation externalDocs) {
this.externalDocs = externalDocs;
return this;
}
3.启动类配置,无论是swagger2还是swagger3,都需要配置
如果项目不存在springMVC配置,仍然报404,肯定是接口地址有问题,例如本项目中,路由地址添加了context-path,如果添加了也要用contact拼接上去
ps:此处要特别注意,如果启动成功,但swagger报404,肯定是接口地址有问题,例如本项目中,路由地址添加了context-path
4.安全问题---解决方案
项目在进行安全扫描时,swagger是很容易收到安全攻击的,因此需要设计一套针对与swagger的安全访问权限,如test表示test环境可以被访问,其他环境不可以被访问
如上图所示,@Profile和@EnableSwaggerBootstrapUI都能够配置swagger访问权限。二者单一使用即可,如需组合使用,需要注意注解的顺序
二者比较而言,@Profile环境权限配置权限较大,故需要注意注解的顺序
@Profile({"test"})//环境权限配置,该权限较大,无论如何都会优先执行第一个权限
@EnableSwaggerBootstrapUI
当使用@EnableSwaggerBootstrapUI注解时,需要在yml文件中配置swagger的访问账号密码
swagger:
# 不可设置为true,否则将屏蔽所有资源
production: false
basic:
enable: true
username: root
password: 123456
如上图所示采用组合方式的权限访问,首先确认环境是否正确,再确认密码正确,全部正确才可以进入访问。如果环境校验不通过,则不会出现输入密码的场景
陈逸轩*^_^*: 虽然我读不懂,但我觉得写的不错
?oK?????: 写的依托答辩
Rice_kil: 写的啥玩意 一点不清晰易读
chatty 陈: 根据getForobject方法自动拼接参数(注意入参如果是map,需要先定义好参数的key,拼接的key要与map定义的字段对应) [code=java] Map<String, Object> map = new HashMap<String, Object>(); //获取整车信息数据,根据getForobject方法自动拼接参数(注意入参如果是map,需要先定义好参数的key,拼接的key要与map定义的字段对应) map = this.realService.getCarRealData(vin); 在查到的map中添加code和msg字段 map.put("CODE", mapAuth.get("CODE")); map.put("msg", mapAuth.get("msg")); return map; List<Map<String,Object>> list = new ArrayList<>(); list.add(realService.getCarRealData(vin)); [/code]
chatty 陈: 在后续docker使用过程中,如果出现步骤10的问题,可操作对应的解决方案,亲测有效