spring boot 集成 swagger2 并定制RestFul API接口

Love The Way You Lie 2022-04-10 03:14 233阅读 0赞

1、添加maven依赖：

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

2、添加配置

@Configuration
    @EnableSwagger2
    public class Swagger2 { 
    
        @Bean
        public Docket createRestApi() { 
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.shengqian.demo"))
                    .paths(PathSelectors.any())
                    .build();
        }
    
        private ApiInfo apiInfo() { 
            return new ApiInfoBuilder()
                    .title("省钱小工具项目接口文档")
                    .description("利用 爬虫等技术构建基于分布式架构下的 api")
                    .termsOfServiceUrl("http://www.chaojilaji.com/")
                    .contact("chaojilaji")
                    .version("1.0")
                    .build();
        }
    }

3、文档学习  
注解：[http://docs.swagger.io/swagger-core/v1.5.X/apidocs/index.html?io/swagger/annotations/ApiResponses.html][http_docs.swagger.io_swagger-core_v1.5.X_apidocs_index.html_io_swagger_annotations_ApiResponses.html]  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3hpZWxpbnJ1aTEyMw_size_16_color_FFFFFF_t_70]  
demo：

@ApiOperation(value="创建用户", notes="用户注册")
    @ApiImplicitParams({ 
            @ApiImplicitParam(name = "username", value = "用户名", required = true, dataType = "String"),
            @ApiImplicitParam(name = "password", value = "密码", required = true, dataType = "String"),
            @ApiImplicitParam(name = "phone", value = "电话号码", required = true, dataType = "String")
    })

为了使返回值的model内有值，需要把返回值也定义成类的格式，比如pojo。

public class UserResponce { 
        private String info;
        private int code;
        private String key;
    
        public String getInfo() { 
            return info;
        }
    
        public int getCode() { 
            return code;
        }
    
        public String getKey() { 
            return key;
        }
    
        public void setInfo(String info) { 
            this.info = info;
        }
    
        public void setCode(int code) { 
            this.code = code;
        }
    
        public void setKey(String key) { 
            this.key = key;
        }
    }
    //修改controller
    public UserResponce userLogin(@RequestParam("phone") final String phone,
                                             @RequestParam("password") final String password,
                                             @RequestParam("ip") final String ip){ 
            UserResponce ans = new UserResponce();
            // TODO: 2018/12/18 验证该phone是否已经登录，不能直接根据这个token是否存在，应该判断时间
            String token = redisService.getTokenFromRedis(phone);
            if (token != ""){ 
                if (jwtService.checkTimeFromToken(token, ip)){ 
                    ans.setCode(300);
                    ans.setInfo("用户已经登录，请半小时后重新尝试");
                    return ans;
                }
            }
            UserInfoDto dto = userInfoService.getUser(phone);
            if (!dto.isRegister()){ 
                dto.setPassword(password);
                UserInfoDto dto1 = userInfoService.checkPassword(dto);
                if (dto1.isVoladate()){ 
                    String key = jwtService.getJwtsString(ip);
                    ans.setCode(200);
                    ans.setInfo("成功");
                    ans.setKey(key);
                    // TODO: 2018/12/18 将key放入redis
                    redisService.insertTokenTORedis(key,phone);
                    return ans;
                }
            }
            ans.setCode(400);
            ans.setInfo("用户名或密码错误");
            return ans;
        }

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3hpZWxpbnJ1aTEyMw_size_16_color_FFFFFF_t_70 1]

使用限制没啥问题了，不过需要解决的是，当项目上线了，如果避免别人访问  
解决办法：  
使用注解@ConditionalOnProperty(name = “swagger.enable”, havingValue = “true”) 然后在测试配置或者开发配置中 添加 swagger.enable = true 即可开启，生产环境不填则默认关闭Swagger.

@Configuration
    @EnableSwagger2
    @ConditionalOnProperty(name = "swagger.enable", havingValue = "true")
    public class Swagger2 { 
    
        @Bean
        public Docket createRestApi() { 
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("cqcdi.web.scm"))
                    .paths(PathSelectors.any())
                    .build();
        }
    
        private ApiInfo apiInfo() { 
            return new ApiInfoBuilder()
                    .title("ccs 接口文档")
                    .description("Copyright © 2018 重庆市信息通信咨询设计院有限公司版权所有")
                    .termsOfServiceUrl("http://www.cqcdi.com/")
                    .contact("chaojilaji")
                    .version("1.0")
                    .build();
        }
    }

然后在配置文件中加入：

swagger.enable=true

将不规范的返回值设置成json：  
@ApiResponce中有一个可选项 responseContainer,解释是：Declares a container wrapping the response.  
Valid values are “List”, “Set” or “Map”. Any other value will be ignored.感兴趣的同学可以自己尝试一下，对于那种接口写得各种奇怪的类型（比如一个Int值，一个Map，怎么做swagger才能进行显示）

[http_docs.swagger.io_swagger-core_v1.5.X_apidocs_index.html_io_swagger_annotations_ApiResponses.html]: http://docs.swagger.io/swagger-core/v1.5.X/apidocs/index.html?io/swagger/annotations/ApiResponses.html
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3hpZWxpbnJ1aTEyMw_size_16_color_FFFFFF_t_70]: /images/20220403/3af3f6a3289c438fb7d73faf14b0222a.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3hpZWxpbnJ1aTEyMw_size_16_color_FFFFFF_t_70 1]: /images/20220403/035f016348cd42a8a4cbe939e11b426c.png