前面我们学习了Spring Boot集成swagger2的具体操作,但swagger2默认是没有权限控制的,也就是说如果是在内网还好,要是在公网上使用,那么对应接口文档信息将出现安全问题。
这篇文章我们就结合SpringBoot中SpringSecurity来进行设置,让通过swagger2生成的接口文档也拥有访问权限,并且不影响其他业务的正常使用。
SpringSecurity
目前Web开发常用的两个安全框架:Apache Shiro和Spring Security,Spring Security本身是Spring社区的一个子架构,相对而言对Spring有更好的支持。
默认情况下,Spring Security提供了权限、角色、登录等功能。关于Spring Security的详细功能我们后面会专门用来介绍。这里我们直接按照步骤集成使用即可。
功能实现
在swagger2集成项目的基础上引入Spring Security的依赖:
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId></dependency> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <optional>true</optional></dependency><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><!-- spring security 鉴权 --><dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-security</artifactId></dependency>
其中spring-boot-starter-security是针对Spring Security框架,Spring Boot提供的对应的starter。
配置application
引入依赖之后,在application中配置对应的配置项:
spring.security.user.name=admin spring.security.user.password=admin
这样,当启动服务时,访问任意链接,默认都会跳转到Spring Security的登录页面。而且上述配置指定了用来登录的用户名和密码。
配置类
关于swagger2的配置类如下:
@Configuration@EnableSwagger2public class Swagger2Config { @Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) // 返回ApiSelectorBuilder实例,用来控制对哪些接口进行展现 .select() // 扫描需要生成API文档的controller所在的包路径 .apis(RequestHandlerSelectors.basePackage("com.secbro.controller")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("Spring Boot 2.x集成Swagger") .description("用户管理 API 1.0 操作文档") .termsOfServiceUrl("http://www.choupangxia.com/") .version("1.0") .contact(new Contact("程序新视界", "http://www.choupangxia.com/", "secbro2@gmail.com")) .build(); }}
之前文章已经讲过,我们这里就不赘述了。我们知道swagger2默认访问的路径为:http://localhost:8080/swagger-ui.html。
下面我们通过对Spring Security的配置,来有针对性的限制swagger2的访问,具体配置如下:
@EnableWebSecuritypublic class WebSecurityConfig extends WebSecurityConfigurerAdapter { /** * http访问控制 */ @Override protected void configure(HttpSecurity http) throws Exception { http.authorizeRequests() .antMatchers("/api/**").permitAll() // 具体接口鉴权交由业务系统shiro或token等机制来控制,这里只控制swagger2相关 .anyRequest().authenticated() .and() .formLogin() .permitAll(); }}
创建一个配置类,然后继承自WebSecurityConfigurerAdapter,并重写其configure方法。在该方法中可以定义具体拦截的url以及登录相关的配置。
其中antMatchers("/api/**").permitAll()是排除原有业务系统的请求地址。
为什么要排除?因为我们现在只是针对swagger2的访问进行限制,而业务系统本身可能已经有具体其他权限限制了,比如已经使用shiro或者使用拦截器等功能进行权限认证了,如果我们这里再进行拦截,业务系统的api可能就无法正常调用了。
anyRequest().authenticated()指定除了业务系统的接口之外,其他的请求(确保其他的只有swagger2的请求)均需要经过security。
and().formLogin().permitAll()指定登录的form表单及权限。
至此,当访问其他业务系统时security不会影响,而当访问swagger2时,便会弹出如下登录框:登录之后,才能看到具体的接口文档信息。而针对接口文档中的业务api的调用,可通过类似antMatchers("/api/**").permitAll()的形式进行逐步排除。
小结
上面我们通过集成SpringSecurity来达到限制swagger2的目的。但在某些情况下我们可能需要让swagger2可直接显示,而其他接口需要登录。这个时候,反向操作即可。
也就是通过排除swagger2的限制来达到目的。不过在这个过程中需要注意的是不能仅仅排除swagger-ui.html,还需排除swagger2所依赖的静态资源,否则也不会正确显示页面。其实这也是很多人会遇到的一个坑。你可以尝试一下。
《SpringBoot视频教程全家桶》的视频课程第一阶段已经录制完成,目前111节课程。后续还会不断新增其他实战场景、组件的内容。同时也会不断补充像本篇文章这样的实战经验。
课程链接:https://edu.csdn.net/course/detail/20369
原创推荐