从零搭建 Spring Boot 后端项目（五）

野性酷女 2023-02-28 05:44 36阅读 0赞

#### 简介 ####

这一小节主要是，整合Swagger2

#### 步骤 ####

*  在pom.xml下添加如下依赖
    
        
                <dependency>
                    <groupId>io.springfox</groupId>
                    <artifactId>springfox-swagger2</artifactId>
                    <version>2.7.0</version>
                </dependency>
        
                
                <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的主页面  
    ![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzIyMTM2NDM5_size_16_color_FFFFFF_t_70]
 *  swagger 还支持接口测试，接下来简单操作下，点击`/redis/getRedis`并点击`Try it out!`按钮  
    ![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzIyMTM2NDM5_size_16_color_FFFFFF_t_70 1]  
    但我们并没有得到值，只得到了如下网页  
    ![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzIyMTM2NDM5_size_16_color_FFFFFF_t_70 2]  
    为什么呢，因为 Spring Security 把`/redis/getRedis`也拦截了，故我们整合Spring Security后，方便开发可暂时在`SecurityConfig`类中的configure(WebSecurity web)方法中添加如下代码，但权限开发时一定要记得注释，要不然会影响权限开发
    
        //如启用以下配置，则放行所有路径，方便开发使用，但权限管理时需注释
                web.ignoring().antMatchers("/**");
 *  添加好后，重新启动，再点击`/redis/getRedis`并点击`Try it out!`按钮，即可获得该值(当然，你要先存，才能取)  
    ![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzIyMTM2NDM5_size_16_color_FFFFFF_t_70 3]
 *  接下来试一下`/redis/setRedis`  
    ![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzIyMTM2NDM5_size_16_color_FFFFFF_t_70 4]
 *  结果成功如下  
    ![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzIyMTM2NDM5_size_16_color_FFFFFF_t_70 5]

#### 项目地址 ####

**项目介绍：**[**从零搭建 Spring Boot 后端项目**][Spring Boot]  
**代码地址：**[**https://github.com/xiaoxiamo/backend-template**][https_github.com_xiaoxiamo_backend-template]

#### 下一篇 ####

[**六、统一请求结果格式**][Link 1]

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzIyMTM2NDM5_size_16_color_FFFFFF_t_70]: /images/20230209/e6ac89a18c7042e1b5dc9c3efba6b348.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzIyMTM2NDM5_size_16_color_FFFFFF_t_70 1]: /images/20230209/1db432d1d7cc498881258dd3baff4029.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzIyMTM2NDM5_size_16_color_FFFFFF_t_70 2]: /images/20230209/4cb59edc16af462d9e4687ed5b0701b9.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzIyMTM2NDM5_size_16_color_FFFFFF_t_70 3]: /images/20230209/28c2ac6ea24a4cca8bffc9a2a213cef2.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzIyMTM2NDM5_size_16_color_FFFFFF_t_70 4]: /images/20230209/ff54cda4ce244db5910698705dab3620.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzIyMTM2NDM5_size_16_color_FFFFFF_t_70 5]: /images/20230209/f51783f6027346d088673ac7f753d10d.png
[Spring Boot]: https://blog.csdn.net/qq_22136439/article/details/107464114
[https_github.com_xiaoxiamo_backend-template]: https://github.com/xiaoxiamo/backend-template
[Link 1]: https://blog.csdn.net/qq_22136439/article/details/107466974