Spring Boot之Swagger

---

零 项目源码

• Swagger源码免费下载

一 Swagger简介

• Swagger官网
• swagger是一款可以根据resutful风格生成的生成的接口开发文档，并且支持做测试的一款中间软件。
• Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。
• Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。
• 目标：使客户端和文件系统作为服务器以同样的速度来更新文件的方法,参数和模型紧密集成到服务器。
• 支持多种语言 （如：Java，PHP等）

• 注意：在正式环境要记得关闭Swagger，一方面出于安全考虑，另一方方面可以节省运行时内存

二 Spring Boot集成Swagger

2.1 环境准备

• 合适的版本匹配
  • JDK1.8+
  • spring boot 2.5.6/2.5.7
  • springfox-swagger-ui 2.9.2
  • springfox-swagger2 2.9.2

     
    <dependency>
        <groupId>io.springfoxgroupId>
        <artifactId>springfox-swagger2artifactId>
        <version>2.9.2version>
    dependency>
    
    
    <dependency>
        <groupId>io.springfoxgroupId>
        <artifactId>springfox-swagger-uiartifactId>
        <version>2.9.2version>
    dependency>
    

• 否则会出现版本冲突出现空指针异常问题

  Failed to start bean 'documentationPluginsBootstrapper'; 
  nested exception is java.lang.NullPointerException
  

2.2 配置Swagger

1. 编写HelloController类，进行测试

   @RestController
   public class HelloController {
       @RequestMapping("/hello")
       public String hello() {
           return "Hello";
       }
   }
   

   
2. 编写配置类SwaggerConfig

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

   

2.3 配置文档信息

1. 配置Docket实例
   • Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swaggger

   //配置docket以配置Swagger具体参数
   @Bean 
   public Docket docket() {
   	return new Docket(DocumentationType.SWAGGER_2);
   }
   

2. 配置ApiInfo属性文档信息

   //配置swagger文档信息apiInfo
       private ApiInfo apiInfo() {
           //作者信息
           Contact contact = new Contact("缘友一世", "https://www.csdn.net/", "[email protected]");
           return new ApiInfo(
                   "Spring Boot集成Swagger",//标题
                   "学习Swagger",//描述
                   "1.0",//版本
                   "http://localhost",//组织连接
                   contact,//联系人信息
                   "Apache 2.0",//许可
                   "http://www.apache.org/licenses/LICENSE-2.0",//许可连接
                   new ArrayList());//拓展
       }
   

   • 记得修改Docket的内容

   @Bean 
   public Docket docket() {
   	return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
   }
   

   

2.4 配置扫描接口

1. 通过select()方法配置扫描接口

   @Bean
   public Docket docket() {
   	return new Docket(DocumentationType.SWAGGER_2)
   	.apiInfo(apiInfo())
   	// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
   	.select()
   	//RequestHandlerSelectors 配置扫描接口的方式
       //basePackage()：扫描指定的包 [主流]
       //any():扫描全部
       //none():不扫描
       //withClassAnnotation():扫描类上的注解 参数为注解的反射对象
       //withMethodAnnotation():扫描方法上的注解
       //.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
       .apis(RequestHandlerSelectors.basePackage("com.yang.controller"))
   	.build();
   }
   

   
2. 配置接口扫描过滤

    @Bean
   public Docket docket1() {
       return new Docket(DocumentationType.SWAGGER_2)
               .apiInfo(apiInfo())
               .groupName("A")
               .select()
               .apis(RequestHandlerSelectors.basePackage("com.yang.controller"))
               //过滤路径
               /*
                   any() // 任何请求都扫描
                   none() // 任何请求都不扫描
                   regex(final String pathRegex) // 通过正则表达式控制
                   ant(final String antPattern) // 通过ant()控制
                */
               .paths(PathSelectors.ant("/yang/**"))
               .build();
   }
   

   

2.5 配置开关Swagger

1. enable()方法，配置是否开启swagger

   @Bean
   public Docket docket() {
   	return new Docket(DocumentationType.SWAGGER_2)
   	.apiInfo(apiInfo())
   	.enable(false) //配置是否启用Swagger，如果是false，在浏览器将无法访问
   	.select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
   	.apis(RequestHandlerSelectors.basePackage("com.yang.controller"))
   	// 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
   	.paths(PathSelectors.ant("/yang/**"))
   	.build();
   }
   

2. 由项目环境动态配置swagger

   • spring配置文件

   #application.properties
   spring.profiles.active=pro
   #application-dev.properties
   server.port=8081
   #application-pro.properties
   server.port=8080
   

   //配置了swagger的docket的bean实例
   //enable 是否开启swagger
   @Bean
   public Docket docket(Environment environment) {
       //设置要显示的Swagger环境
       Profiles profiles = Profiles.of("dev", "test");
       //获取项目的环境
       //通过environment.acceptsProfiles判断是否处于设定的环境中
       boolean flag = environment.acceptsProfiles(profiles);
   
       return new Docket(DocumentationType.SWAGGER_2)
               .apiInfo(apiInfo())
               .enable(flag)
               .groupName("缘友一世")
               .select()
               //RequestHandlerSelectors 配置扫描接口的方式
               //basePackage()：扫描指定的包 [主流]
               //any():扫描全部
               //none():不扫描
               //withClassAnnotation():扫描类上的注解 参数为注解的反射对象
               //withMethodAnnotation():扫描方法上的注解
               //.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
               .apis(RequestHandlerSelectors.basePackage("com.yang.controller"))
               //过滤路径
               /*
                   any() // 任何请求都扫描
                   none() // 任何请求都不扫描
                   regex(final String pathRegex) // 通过正则表达式控制
                   ant(final String antPattern) // 通过ant()控制
                */
               .paths(PathSelectors.ant("/yang/**"))
               .build();
   }
   

   import org.springframework.context.annotation.Bean;
   import org.springframework.context.annotation.Configuration;
   import org.springframework.core.env.Environment;
   import org.springframework.core.env.Profiles;
   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;
   
   /**
    * @author 缘友一世
    * date 2023/1/27-21:25
    */
   @Configuration
   //开启swagger2
   @EnableSwagger2
   public class SwaggerConfig {
   
       @Bean
       public Docket docket1() {
           return new Docket(DocumentationType.SWAGGER_2)
                   .apiInfo(apiInfo())
                   .groupName("A")
                   .select()
                   .apis(RequestHandlerSelectors.basePackage("com.yang.controller"))
                   //过滤路径
                   /*
                       any() // 任何请求都扫描
                       none() // 任何请求都不扫描
                       regex(final String pathRegex) // 通过正则表达式控制
                       ant(final String antPattern) // 通过ant()控制
                    */
                   .paths(PathSelectors.ant("/yang/**"))
                   .build();
       }
       @Bean
       public Docket docket2() {
           return new Docket(DocumentationType.SWAGGER_2)
                   .groupName("B");
       }
       @Bean
       public Docket docket3() {
           return new Docket(DocumentationType.SWAGGER_2).groupName("C");
       }
       //配置了swagger的docket的bean实例
       //enable 是否开启swagger
       @Bean
       public Docket docket(Environment environment) {
           //设置要显示的Swagger环境
           Profiles profiles = Profiles.of("dev", "test");
           //获取项目的环境
           //通过environment.acceptsProfiles判断是否处于设定的环境中
           boolean flag = environment.acceptsProfiles(profiles);
   
           return new Docket(DocumentationType.SWAGGER_2)
                   .apiInfo(apiInfo())
                   .enable(flag)
                   .groupName("缘友一世")
                   .select()
                   //RequestHandlerSelectors 配置扫描接口的方式
                   //basePackage()：扫描指定的包 [主流]
                   //any():扫描全部
                   //none():不扫描
                   //withClassAnnotation():扫描类上的注解 参数为注解的反射对象
                   //withMethodAnnotation():扫描方法上的注解
                   //.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                   .apis(RequestHandlerSelectors.basePackage("com.yang.controller"))
                   //过滤路径
                   /*
                       any() // 任何请求都扫描
                       none() // 任何请求都不扫描
                       regex(final String pathRegex) // 通过正则表达式控制
                       ant(final String antPattern) // 通过ant()控制
                    */
                   .paths(PathSelectors.ant("/yang/**"))
                   .build();
       }
       //配置swagger文档信息apiInfo
       private ApiInfo apiInfo() {
           //作者信息
           Contact contact = new Contact("缘友一世", "https://www.csdn.net/", "[email protected]");
           return new ApiInfo(
                   "Spring Boot集成Swagger",//标题
                   "学习Swagger",//描述
                   "1.0",//版本
                   "http://localhost",//组织连接
                   contact,//联系人信息
                   "Apache 2.0",//许可
                   "http://www.apache.org/licenses/LICENSE-2.0",//许可连接
                   new ArrayList());//拓展
       }
   }
   
   

   

2.6 配置API分组

1. 通过groupName()方法即可配置分组

   • 如果没有配置分组，默认是default

   @Bean
   public Docket docket(Environment environment) {
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
   	.groupName("hello") // 配置分组
   	// 省略配置....
   }
   

2. 多个分组，需要配置多个docket

   @Bean
   public Docket docket1() {
       return new Docket(DocumentationType.SWAGGER_2)
               .apiInfo(apiInfo())
               .groupName("A")
               .select()
               .apis(RequestHandlerSelectors.basePackage("com.yang.controller"))
               //过滤路径
               /*
                   any() // 任何请求都扫描
                   none() // 任何请求都不扫描
                   regex(final String pathRegex) // 通过正则表达式控制
                   ant(final String antPattern) // 通过ant()控制
                */
               .paths(PathSelectors.ant("/yang/**"))
               .build();
   }
   @Bean
   public Docket docket2() {
       return new Docket(DocumentationType.SWAGGER_2)
               .groupName("B");
   }
   @Bean
   public Docket docket3() {
       return new Docket(DocumentationType.SWAGGER_2).groupName("C");
   }
   

   

2.7 配置实体类

1. 创建实体类

   import io.swagger.annotations.ApiModel;
   import io.swagger.annotations.ApiModelProperty;
   
   /**
    * @author 缘友一世
    * date 2023/1/28-10:21
    */
   
   @ApiModel("用户实体类")
   public class User {
       @ApiModelProperty("用户名")
       public String username;
       @ApiModelProperty("密码")
       public String password;
   }
   
   

   • @ApiModel为类添加注释
   • @ApiModelProperty为类属性添加注释

2. 请求接口映射到实体类

   • 只要这个实体在请求接口的返回值上（即使是泛型），都能映射到实体项中

   @RequestMapping("/getUser")
   public User getUser(){
   	return new User();
   }
   

   

   • 注：只要出现在接口方法的返回值上的实体都会显示，而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的

2.8 常用注解

• 注解所在位置：io.swagger.annotations包下

Swagger注解	简单说明
@Api(tags = “模块说明”)	作用在模块类上
@ApiOperation(“接口说明”)	作用在接口方法上
@ApiModel(“POJO说明”)	作用在模型类上：如VO、BO
@ApiModelProperty(value = “属性说明”,hidden = true)	作用在类方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam(“参数说明”)	作用在参数、方法和字段上，类似@ApiModelProperty