从零搭建 Spring Boot 后端项目（五）-蒲公英云

简介

这一小节主要是，整合Swagger2

步骤

在pom.xml下添加如下依赖

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

在com.example.backend_template.config下新建Swagger2Config类

package com.example.backend_template.config;
import org.springframework.beans.factory.annotation.Value;
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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
 * @ClassName Swagger2Config swagger的配置内容即是创建一个Docket实例
 * @Description 
 * @Author L
 * @Date Create by 2020/6/30
 */
@Configuration
@EnableSwagger2 //启用swagger2
public class Swagger2Config {
    //是否开启 swagger-ui 功能，默认为false
    @Value("${swagger.enable:false}")
    private Boolean enable;
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(enable)
                .pathMapping("/")
                .apiInfo(apiInfo())
                .select()
                //需要Swagger描述的接口包路径，如果不想某接口暴露，可在接口上加@ApiIgnore注解
                .apis(RequestHandlerSelectors.basePackage("com.example.backend_template.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    //配置在线文档的基本信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("BackendTemplate项目")
                .description("使基于SpringBoot的后端开发变得简单")
                .version("1.0")
                .build();
    }
}

在application-dev.properties中添加如下配置
```
# Swagger
# 是否启用Swagger
swagger.enable=true
```

使用 swagger 注解

@Api注解可以用来描述当前Controller的功能
@ApiOperation注解用来描述Controller的方法的作用
@ApiResponses 用在Controller的方法上，说明Response集
@ApiResponse 用在@ApiResponses里边
@ApiImplicitParam注解用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入
如果有多个参数，则需要使用多个@ApiImplicitParam注解来描述，多个@ApiImplicitParam注解需要放在一个@ApiImplicitParams注解中
@ApiModel 描述实体对象或响应对象的意义，用在pojo类上
@ApiModelProperty 用在实体对象或响应对象的字段上，描述其属性

使用以上注解，并简单修改下原RedisController类，修改后的内容如下：

package com.example.backend_template.controller;
import com.example.backend_template.service.RedisService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
import javax.annotation.Resource;
/**
 * @ClassName RedisController
 * @Description 
 * @Author L
 * @Date Create by 2020/6/26
 */
@Api(tags = "redis简单测试接口")
@RestController
@RequestMapping("redis")
public class RedisController {
    @Resource
    private RedisService redisService;
    @ApiOperation("向redis中存储`name`值")
    @ApiImplicitParam(name = "name",value = "名称值",defaultValue = "L",required = true)
    @PostMapping("/setRedis")
    public Boolean setRedis(@RequestBody String name) {
        return redisService.set("name", name);
    }
    @ApiOperation("向redis中取`name`值")
    @GetMapping("/getRedis")
    public String getRedis() {
        return redisService.get("name");
    }
}

此时我们因为在项目中已整合了 Spring Security ，那么如果不做额外配置，Swagger2文档路径就会被拦截，此时只需要在Spring Security的配置类SecurityConfig.java中重写父类configure(WebSecurity web)方法，就不会被Spring Security拦截了，修改security/SecurityConfig类为如下代码：

package com.example.backend_template.security;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.authentication.builders.AuthenticationManagerBuilder;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.builders.WebSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.util.DigestUtils;

/**
- @ClassName SecurityConfig
- @Description
- @Author L
- @Date Create by 2020/6/30
  */
  @Configuration
  @EnableWebSecurity
  public class SecurityConfig extends WebSecurityConfigurerAdapter {
  @Autowired
  private UserDetailsServiceImpl userService;
  @Autowired
  public void configureGlobal(AuthenticationManagerBuilder auth) throws Exception {
```
 //校验用户
 auth.userDetailsService(userService).passwordEncoder(new PasswordEncoder() {
     //对密码进行加密
     @Override
     public String encode(CharSequence charSequence) {
         return DigestUtils.md5DigestAsHex(charSequence.toString().getBytes());
     }
     //对密码进行判断匹配
     @Override
     public boolean matches(CharSequence charSequence, String s) {
         String encode = DigestUtils.md5DigestAsHex(charSequence.toString().getBytes());
         boolean res = s.equals(encode);
         return res;
     }
 });
```
  }
  
  @Override
  protected void configure(HttpSecurity http) throws Exception {
```
 http.authorizeRequests()
         .antMatchers("/", "/index", "/login", "/login-error", "/401").permitAll()
         .anyRequest().authenticated()
         .and()
         .formLogin().loginPage("/login").failureUrl("/login-error")
         .and()
         .exceptionHandling().accessDeniedPage("/401");
 http.logout().logoutSuccessUrl("/");
```
  }
  
  //使Spring Security不拦截swagger相关文档，以下路径不会经过过滤链
  @Override
  public void configure(WebSecurity web) throws Exception {
```
 //放行swagger
 web.ignoring().antMatchers(
         "/v2/api-docs",
         "/swagger-resources",
         "/swagger-resources/**",
         "/configuration/ui",
         "/configuration/security",
         "/swagger-ui.html/**",
         "/webjars/**");
 //如启用以下配置，则放行所有路径，方便开发使用，但权限管理时需注释
 //web.ignoring().antMatchers("/**");
```
  }
  }

测试

启动backen_template项目，并访问 http://localhost:8080/swagger-ui.html ，出现以下内容即为swagger的主页面
swagger 还支持接口测试，接下来简单操作下，点击/redis/getRedis并点击Try it out!按钮

但我们并没有得到值，只得到了如下网页

为什么呢，因为 Spring Security 把/redis/getRedis也拦截了，故我们整合Spring Security后，方便开发可暂时在SecurityConfig类中的configure(WebSecurity web)方法中添加如下代码，但权限开发时一定要记得注释，要不然会影响权限开发
```
//如启用以下配置，则放行所有路径，方便开发使用，但权限管理时需注释
        web.ignoring().antMatchers("/**");
```
添加好后，重新启动，再点击/redis/getRedis并点击Try it out!按钮，即可获得该值(当然，你要先存，才能取)
接下来试一下/redis/setRedis
结果成功如下