Springboot集成Swagger

1. Swagger简介

1.1 前后端分离发展历史

后端时代：

前段只用管静态页面；html==>后端。模版引擎JSP=>后端是助理

前后端分离时代：

后端：后端控制层，服务层，数据访问层次【后端团队】

前段：前端控制层，视图层【前段团队】。 伪造后端数据json已经存在了，不需要后端，前段工程依旧可以跑起来。

那么问题来了？

前后端如何交互？===》API

前后端相对独立，松耦合

前后端甚至可以部署在不同的服务器上

生产一个问题：

前后端集成联调，前后端人员无法做到“及时协商，尽早解决”，导致问题集中爆发。

首先指定一个schema，实时更新最新的api，降低集成风险。

早些年，制定word文档

前后端分离：前端测试后端接口：post； 后端提供接口，需要实时更新最新的消息以及改动

1.2 Swagger产生

Swagger:

• 号称世界上最流行的API框架
• Restful Api文档在线自动生成工具=>API文档与API定义同步更新
• 直接运行，在线测试API接口
• 支持多种语言
• 官网地址：https://swagger.io/

2. SpringBoot集成Swagger 

2.1初步集成swagger

1. 新建一个Springboot-web项目，编写一个hello工程

2. 导入相关依赖

   <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
   <dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger2</artifactId>
     <version>2.9.2</version>
   </dependency>
   <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
   <dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger-ui</artifactId>
     <version>2.9.2</version>
   </dependency>

3. 配置Swagger

   @Configuration //配置类
   @EnableSwagger2// 开启Swagger2的自动配置
   public class SwaggerConfig {
   }

4. 测试运行 http://localhost:8080/swagger-ui.html   ；包含四部分：Swagger信息 接口信息 实体信息 组
5. 配置Swagger扫描接口

   package com.study.cloud.config;
   
   import org.springframework.context.annotation.Bean;
   import org.springframework.context.annotation.Configuration;
   import org.springframework.context.annotation.Profile;
   import org.springframework.core.env.Environment;
   import org.springframework.core.env.Profiles;
   import springfox.documentation.RequestHandler;
   import springfox.documentation.builders.PathSelectors;
   import springfox.documentation.builders.RequestHandlerSelectors;
   import springfox.documentation.service.ApiInfo;
   import springfox.documentation.service.Contact;
   import springfox.documentation.spi.DocumentationType;
   import springfox.documentation.spring.web.plugins.Docket;
   import springfox.documentation.swagger2.annotations.EnableSwagger2;
   
   import java.util.ArrayList;
   
   @Configuration //配置类
   @EnableSwagger2// 开启Swagger2的自动配置
   public class SwaggerConfig {
       @Bean
       public Docket docket(Environment environment){
           Profiles profiles = Profiles.of("dev","test");
           boolean flag = environment.acceptsProfiles(profiles);
           return  new Docket(DocumentationType.SWAGGER_2)
                   .apiInfo(apiInfo())
                   .groupName("Cloud2022组")//分组名称不能有空格
                   .enable(flag)//通过enable()方法配置是否启用swagger，如果是false，swagger将不能在浏览器中访问了
                   .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
                       /*
                        any() // 扫描所有，项目中的所有接口都会被扫描到
                        none() // 不扫描接口
                        withMethodAnnotation(final Class<? extends Annotation> annotation)// 通过方法上的注解扫描
                        withClassAnnotation(final Class<? extends Annotation> annotation)// 通过类上的注解扫描，
                        basePackage(final String basePackage) // 根据包路径扫描接口;
                       */
                   .apis(RequestHandlerSelectors.any())
                   /*  any() // 任何请求都扫描
                       none() // 任何请求都不扫描
                       regex(final String pathRegex) // 通过正则表达式控制
                       ant(final String antPattern) // 通过ant()控制 * */
                   .paths(PathSelectors.ant("/**"))// // 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
                   .build();
   
       }
       @Bean
       public Docket docketA( ){
           return  new Docket(DocumentationType.SWAGGER_2).groupName("A");
       }
       @Bean
       public Docket docketB( ){
           return  new Docket(DocumentationType.SWAGGER_2).groupName("B");
       }
       @Bean
       public Docket docketC( ){
           return  new Docket(DocumentationType.SWAGGER_2).groupName("C");
       }
       @Bean
       public Docket docketD( ){
           return  new Docket(DocumentationType.SWAGGER_2).groupName("D");
       }
   
       private ApiInfo apiInfo(){
           Contact contact = new Contact("gzm", "", "");
           return new ApiInfo("Cloud 2022 API文档"
                           , "描述:API文档描述！"
                           , "1.0"
                           , "urn:tos"
                           , contact
                           , "Apache 2.0"
                           , "http://www.apache.org/licenses/LICENSE-2.0"
                           , new ArrayList());
       }
   
   
   }

    

6. @Api(tags = "xxx模块说明")作用在模块类上
   @ApiOperation("xxx接口说明")作用在接口方法上
   @ApiModel("xxxPOJO说明")作用在模型类上：如VO、BO
   @ApiModelProperty(value = "xxx属性说明",hidden = true)作用在类方法和属性上，hidden设置为true可以隐藏该属性@ApiParam("xxx参数说明")作用在参数、方法和字段上， 类似@ApiModelProperty

 注意： 1. 如果配置类所属的包不是启动类的同级或子级则需要在启动累上自己指定需要扫描对应路径，例如：@ComponentScan("com.xxx.xxx.config")

             2. 多分组即配置多个Docket实例，名称不能有空格

             3. swagger能不能扫描到提示 与有没有api注解无关， 只要返回值中有这个实例 就可以扫描到

总结：

相较于传统的Postman或Curl方式测试接口，使用swagger简直就是傻瓜式操作，不需要额外说明文档(写得好本身就是文档)而且更不容易出错，只需要录入数据然后点击Execute，如果再配合自动化框架，可以说基本就不需要人为操作了。

Swagger是个优秀的工具，现在国内已经有很多的中小型互联网公司都在使用它，相较于传统的要先出Word接口文档再测试的方式，显然这样也更符合现在的快速迭代开发行情。当然了，提醒下大家在正式环境要记得关闭Swagger，一来出于安全考虑二来也可以节省运行时内存。