SpringBoot项目集成使用Swagger

我不是女神ヾ 2022-12-02 10:54 95阅读 0赞

## 一、简介 ##

### 前后端分离 ###

*  后端时代：
    
    前端只用管理静态页面；html==>后端（前端编写HTML等样式交给后端），模板引擎JSP=>后端是主力
 *  前后端分离时代：
    
     *  后端：后端控制层，服务层，数据访问层
     *  前端：前端控制层（如vue中的双向绑定，通过data渲染等），视图层
        
         *  前端伪造后端数据，json在前端写的时候已经存在，不需要后端，前端工程依旧能够跑起来
     *  前后端如何交互？===>通过API接口进行交互
     *  前后端相对独立，松耦合；
     *  前后端甚至可以部署在不同的服务器上
 *  产生问题：
    
    前后端集成联调，前端人员和后端人员无法做到“及时协商，尽早解决”，最终导致问题集中爆发，容易导致工程延期。
 *  解决方案：
    
     *  首先指定schema\[计划的提纲\]，实时更新最新API，降低集成的风险；
     *  早先年：指定word计划文档；
     *  前后端分离：
        
         *  前端测试后端接口：postman（一个API接口，用来测试请求）
         *  后端提供接口，需要实时更新最新的消息及改动！
 *  **Swagger**
    
     *  号称世界上最流行的API框架；
     *  RestFul Api 风格文档在线自动生成工具=>Api文档与Api定义同步更新
     *  可以直接运行，可以在线测试API接口；
     *  支持多种语言（Java、Php…）
    
    [官网链接][Link 1]

## 二、在SpringBoot项目中使用Swagger ##

### 1.在项目中使用Swagger需要导入jar包 ###

*  Springfox Swagger2
 *  Springfox Swagger UI

### 2. SpringBoot中集成Swagger ###

*  新建一个SpringBoot-Web项目
 *  导入相关依赖
    
        
        <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>
 *  编写一个HelloWorld工程
    
    测试项目是否搭建成功
    
        package com.sly.swaggertest.controller;
        
        
        import org.springframework.web.bind.annotation.RequestMapping;
        import org.springframework.web.bind.annotation.RestController;
        
        @RestController
        public class HelloController { 
        
        
            @RequestMapping(value = "/hello")
            public String hello(){ 
                return "hello";
            }
        }
 *  配置S wagger==>Config
    
    （最基础的使用，使用的都是默认配置）
    
        package com.sly.swaggertest.config;
        
        
        import org.springframework.context.annotation.Configuration;
        import springfox.documentation.swagger2.annotations.EnableSwagger2;
        
        @Configuration
        @EnableSwagger2 //开启Swagger2
        public class SwaggerConfig { 
            
        }
 *  测试与运行，访问http://localhost:8080/swagger-ui.html
    
    \[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQzNjEyNzA0_size_16_color_FFFFFF_t_70_pic_center][]  
    上传(img-29LgBT2J-1598774031934)(C:\\Users\\dell\\Pictures\\Saved Pictures\\Swagger学习1.png)\]

### 3.配置Swagger ###

#### 基本信息配置 ####

@Configuration
    @EnableSwagger2 //开启Swagger2
    public class SwaggerConfig { 
    /* 配置Swagger的Docket的Bean实例 用Docket对象接管了Swagger原来的默认配置 */
        @Bean
        public Docket docket(){ 
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo());
        }
    
    // 配置Swagger信息=apiInfo
        private ApiInfo apiInfo(){ 
    // 作者信息
            Contact contact = new Contact("XXXX","https://mp.csdn.net/console/article","XXXXXXXX@qq.com");
            return new ApiInfo(
                    "Swagger学习日记",
                    "SpringBoot配置Swagger",
                    "v1.0",
                    "https://www.icourse163.org/learn/HIT-309001?tid=1450232446#/learn/content?type=detail&id=1214541616&cid=1218328471&replay=true",
                    contact,
                    "Apache 2.0",
                    "http://www.apache.org/licenses/LITCENSE-2.0",
                    new ArrayList<>()
            );
    
        }
    
    }

扫描到的包：

\[外链图片转存失败,源站可能有防盗链机制,建议)  
将图片保存下来直接上传(img-rGqBtZba-1598774031938)(C:\\Users\\dell\\Pictures\\S![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQzNjEyNzA0_size_16_color_FFFFFF_t_70_pic_center 1]  
aved Pictures\\Swagger学习2.png)\]

#### 配置扫描接口 ####

**接口过滤相关**

@Bean
        public Docket docket(){ 
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
    // RequestHandlerSelectors配置需要扫描接口的方式
    // basePackage()指定要扫描的包***用的比较多***
    // any()扫描全部的包
    // none()都不扫描
    // withClassAnnotation扫描类上的注解,参数是一个注解的反射对象
    // withMethodAnnotation扫描方法上的注解
                    .apis(RequestHandlerSelectors.basePackage("com.sly.swaggertest.controller"))
    // paths()过滤什么路径
                    .paths(PathSelectors.ant("/sly/**"))
                    .build();//build是设计模式中的建造者模式
        }

配置接口过滤后扫描到的包：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQzNjEyNzA0_size_16_color_FFFFFF_t_70_pic_center 2]

*  配置是否启用Swagger

//enable用来配置是否启用Swagger，如果为false则Swagger不能在浏览器中访问 
    .apiInfo(apiInfo())
     .enable(false)

![在这里插入图片描述][20200830155719984.png_pic_center]

#### 只希望Swagger在生产环境使用，在发布的时候不使用应该怎么办？ ####

*  判断是不是生产环境 flag=false
 *  注入enable(flag)

**具体操作：**

*  在SpringBoot项目中给生产和发布环境建立不同的配置文件，可以就可以通过配置文件实现环境的切换  
    ![在这里插入图片描述][20200830161047733.png_pic_center]  
    ![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQzNjEyNzA0_size_16_color_FFFFFF_t_70_pic_center 3]

#### 配置API文档的分组 ####

.groupName("ICES")

![在这里插入图片描述][20200830161129497.png_pic_center]

*  **配置多个分组**
    
    新建多个Docket实例即可，在配置了多个实例以后就可以多个人协同开发了
    
        @Bean
            public Docket docket1(){ 
                return new Docket(DocumentationType.SWAGGER_2).groupName("aaa");
            }
            @Bean
            public Docket docket2(){ 
                return new Docket(DocumentationType.SWAGGER_2).groupName("bbb");
            }
            @Bean
            public Docket docket3(){ 
                return new Docket(DocumentationType.SWAGGER_2).groupName("ccc");
            }
            @Bean
            public Docket docket4(){ 
                return new Docket(DocumentationType.SWAGGER_2).groupName("ddd");
            }

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQzNjEyNzA0_size_16_color_FFFFFF_t_70_pic_center 4]

#### 实体类的配置 ####

光有实体类，实体类和Swagger的配置中是不能产生任何联系，不能被扫描到的，但只要我们的接口的返回值中存在某一实体类，那么这个实体类就会被扫描到Swagger中

@PostMapping(value = "/user")
        public User user(){ 
            return new User();
        }

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQzNjEyNzA0_size_16_color_FFFFFF_t_70_pic_center 5]  
在实体类很复杂时，就算能扫描到，但是在前后端协同开发的时候前端人员可能还是不知道实体类和其中变量的含义，所以我们要在实体类及其变量上添加注释

@ApiModel("用户实体类")//给实体类的注释
    public class User { 
        @ApiModelProperty("用户名")//给变量的注释
        public String username;
        @ApiModelProperty("密码")
        public String password;
    
    }

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQzNjEyNzA0_size_16_color_FFFFFF_t_70_pic_center 6]

给接口和函数的参数加上注释

@ApiOperation("hello控制类")
    @GetMapping(value = "/hello2")
    public String hello2(@ApiParam("用户名") String username){ 
        return "hello"+username;
    }

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQzNjEyNzA0_size_16_color_FFFFFF_t_70_pic_center 7]

**点击上图的Try it Out还可以对后端接口接口进行测试**

#### 总结（Swagger用处）： ####

*  实现接口文档的实时更新，便于合作开发
 *  可以通过Swagger给一些比较难理解的属性或者接口增加注释信息
 *  可以对后端接口进行在线测试

[Link 1]: https://swagger.io/
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQzNjEyNzA0_size_16_color_FFFFFF_t_70_pic_center]: /images/20221123/5b5c971995b64b46b110e914904ed26a.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQzNjEyNzA0_size_16_color_FFFFFF_t_70_pic_center 1]: /images/20221123/daf00f4cf41d43708005c65708cc502f.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQzNjEyNzA0_size_16_color_FFFFFF_t_70_pic_center 2]: /images/20221123/9f6d676516ab4ce09a0164434982abfe.png
[20200830155719984.png_pic_center]: /images/20221123/f9e74470df5f4d6dba3680954a30cbd2.png
[20200830161047733.png_pic_center]: /images/20221123/49a79089de6d42c994579983f7eaaa85.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQzNjEyNzA0_size_16_color_FFFFFF_t_70_pic_center 3]: /images/20221123/cdfebcc7ee2c4bd78f7c8734e350be68.png
[20200830161129497.png_pic_center]: /images/20221123/c69faf7130df4cb88795f3ccdc8a2e14.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQzNjEyNzA0_size_16_color_FFFFFF_t_70_pic_center 4]: /images/20221123/8d93f4600d2b4f7cb93fdf11a1895d0d.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQzNjEyNzA0_size_16_color_FFFFFF_t_70_pic_center 5]: /images/20221123/686f348ad0d74dd8902cbd7b3a66c316.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQzNjEyNzA0_size_16_color_FFFFFF_t_70_pic_center 6]: /images/20221123/d961ee76d4fe4ddda0f299a2127f4e29.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQzNjEyNzA0_size_16_color_FFFFFF_t_70_pic_center 7]: /images/20221123/833b519bd20b4038b8816b7138cc4bd1.png