Springboot集成Swagger

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

2. 导入相关依赖

    1 <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
    2 <dependency>
    3   <groupId>io.springfox</groupId>
    4   <artifactId>springfox-swagger2</artifactId>
    5   <version>2.9.2</version>
    6 </dependency>
    7 <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
    8 <dependency>
    9   <groupId>io.springfox</groupId>
   10   <artifactId>springfox-swagger-ui</artifactId>
   11   <version>2.9.2</version>
   12 </dependency>

3. 配置Swagger

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

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

    1 package com.study.cloud.config;
    2 
    3 import org.springframework.context.annotation.Bean;
    4 import org.springframework.context.annotation.Configuration;
    5 import org.springframework.context.annotation.Profile;
    6 import org.springframework.core.env.Environment;
    7 import org.springframework.core.env.Profiles;
    8 import springfox.documentation.RequestHandler;
    9 import springfox.documentation.builders.PathSelectors;
   10 import springfox.documentation.builders.RequestHandlerSelectors;
   11 import springfox.documentation.service.ApiInfo;
   12 import springfox.documentation.service.Contact;
   13 import springfox.documentation.spi.DocumentationType;
   14 import springfox.documentation.spring.web.plugins.Docket;
   15 import springfox.documentation.swagger2.annotations.EnableSwagger2;
   16 
   17 import java.util.ArrayList;
   18 
   19 @Configuration //配置类
   20 @EnableSwagger2// 开启Swagger2的自动配置
   21 public class SwaggerConfig {
   22     @Bean
   23     public Docket docket(Environment environment){
   24         Profiles profiles = Profiles.of("dev","test");
   25         boolean flag = environment.acceptsProfiles(profiles);
   26         return  new Docket(DocumentationType.SWAGGER_2)
   27                 .apiInfo(apiInfo())
   28                 .groupName("Cloud2022组")//分组名称不能有空格
   29                 .enable(flag)//通过enable()方法配置是否启用swagger，如果是false，swagger将不能在浏览器中访问了
   30                 .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
   31                     /*
   32                      any() // 扫描所有，项目中的所有接口都会被扫描到
   33                      none() // 不扫描接口
   34                      withMethodAnnotation(final Class<? extends Annotation> annotation)// 通过方法上的注解扫描
   35                      withClassAnnotation(final Class<? extends Annotation> annotation)// 通过类上的注解扫描，
   36                      basePackage(final String basePackage) // 根据包路径扫描接口;
   37                     */
   38                 .apis(RequestHandlerSelectors.any())
   39                 /*  any() // 任何请求都扫描
   40                     none() // 任何请求都不扫描
   41                     regex(final String pathRegex) // 通过正则表达式控制
   42                     ant(final String antPattern) // 通过ant()控制 * */
   43                 .paths(PathSelectors.ant("/**"))// // 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
   44                 .build();
   45 
   46     }
   47     @Bean
   48     public Docket docketA( ){
   49         return  new Docket(DocumentationType.SWAGGER_2).groupName("A");
   50     }
   51     @Bean
   52     public Docket docketB( ){
   53         return  new Docket(DocumentationType.SWAGGER_2).groupName("B");
   54     }
   55     @Bean
   56     public Docket docketC( ){
   57         return  new Docket(DocumentationType.SWAGGER_2).groupName("C");
   58     }
   59     @Bean
   60     public Docket docketD( ){
   61         return  new Docket(DocumentationType.SWAGGER_2).groupName("D");
   62     }
   63 
   64     private ApiInfo apiInfo(){
   65         Contact contact = new Contact("gzm", "", "");
   66         return new ApiInfo("Cloud 2022 API文档"
   67                         , "描述:API文档描述！"
   68                         , "1.0"
   69                         , "urn:tos"
   70                         , contact
   71                         , "Apache 2.0"
   72                         , "http://www.apache.org/licenses/LICENSE-2.0"
   73                         , new ArrayList());
   74     }
   75 
   76 
   77 }

    

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

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

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