SpringBoot整合Springfox-Swagger2

ゝ一世哀愁。 2023-01-04 14:31 221阅读 0赞

# [SpringBoot整合Springfox-Swagger2 ][SpringBoot_Springfox-Swagger2] #

前言

不管Spring Boot整合还是SpringMVC整合Swagger都基本类似，重点就在于配置Swagger，它的精髓所在就在于配置。  
@

*  [1、Swagger简介][1_Swagger]
 *  [2、整合前可能遇到的问题][2]
 *  [3、SpringBoot集成Swagger][3_SpringBoot_Swagger]
 *  [4、配置Swagger][4_Swagger]
    
     *  [4.1、Swagger四部分布局][4.1_Swagger]
     *  [4.2、第二部分：API基本信息][4.2_API]
        
         *  [1、分析][1]
         *  [2、RequestHandlerSelectors过滤][2_RequestHandlerSelectors]
     *  [4.3、第一部分：配置API分组][4.3_API]
     *  [4.4、Swagger2的常用注解][4.4_Swagger2]
     *  [4.5、第三部分：API请求列表][4.5_API]
     *  [4.6、第四部分：API实体列表][4.6_API]

## 1、Swagger简介 ##

目前互联网时代前后端分离已成趋势，前后端混在一起，前端或者后端无法做到“及时协商，尽早解决”，最终导致问题集中爆发。解决方案就是前后端通过API进行交互达到相对独立且松耦合。`Swagger`就是这样的一个API框架，`Swagger`支持多种语言 如：`Java`，`PHP`等，它号称是世界上最流行的API框架！

## 2、整合前可能遇到的问题 ##

1、  
导入好依赖jar包之后，使用注解说找不到之类的问题，如遇到，请参考：[所有Intellij IDEA Cannot Resolve Symbol XXX问题的解决方法汇总][Intellij IDEA Cannot Resolve Symbol XXX]

2、  
版本问题，SpringBoot的版本很多，被集成的框架版本也很多，可能版本高一点或者低一点就可能出现各种bug，这是集成其他框架的通病，这里得注意一下。如果运行出现一些什么bug，如果对SpringBoot底层原理不是很了解的可以先百度谷歌一下，找不到建议不妨**换个SpringBoot的版本**！

## 3、SpringBoot集成Swagger ##

> **注意：jdk 1.8以上才能运行swagger2**

1、  
导入两个jar包依赖

<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>

2、  
要想使用Swagger，必须编写一个配置类来配置 Swagger，这里的配置类如下

@Configuration //说明这是一个配置类
    @EnableSwagger2// 该注解开启Swagger2的自动配置
    public class SwaggerConfig {  //随便的一个类名
    
    }

3、  
这个时候已经算是初步整合完毕了，启动项目可访问`http://localhost:8080/swagger-ui.html` 可以看到swagger的界面，如下；  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQ0NTQzNTA4_size_16_color_FFFFFF_t_70]

## 4、配置Swagger ##

不管是Spring Boot整合还是SpringMVC整合Swagger都基本类似，重点就在于配置Swagger，它的精髓所在就在于配置，这很关键。我们从下图来全局看看Swagger的四部分重点布局：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQ0NTQzNTA4_size_16_color_FFFFFF_t_70 1]

### 4.1、Swagger四部分布局 ###

> **Swagger实例Bean是Docket，所以必须通过配置Docket实例来配置Swaggger。**

第一部分--API分组：如果没有配置分组默认是default。通过Swagger实例Docket的`groupName()`方法即可配置分组  
第二部分--基本描述：可以通过Swagger实例Docket的`apiInfo()`方法中的ApiInfo实例参数配置文档信息  
第三部分--请求接口列表：在组范围内，只要被Swagger2扫描匹配到的请求都会在这里出现。  
第四部分--实体列表：只要实体在请求接口的返回值上（即使是泛型），都能映射到实体项中！

> 第四部分注意：并不是因为@ApiModel注解让实体显示在Models列表里，而是只要出现在接口方法的返回值上的实体都会显示在这里，而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的。前者为类添加注释，后者为类属性添加注释。

### 4.2、第二部分：API基本信息 ###

先从第二部分开始分析，这样分析对理解第一部分比较有帮助。

@Configuration
    @EnableSwagger2
    @ComponentScan("com.yichun.swagger_boot_demo.controller")
    public class SwaggerConfig {
        @Bean
        public Docket docker(){
            // 构造函数传入初始化规范，这是swagger2规范
            return new Docket(DocumentationType.SWAGGER_2)
                    //apiInfo： 添加api详情信息，参数为ApiInfo类型的参数，这个参数包含了第二部分的所有信息比如标题、描述、版本之类的，开发中一般都会自定义这些信息
                    .apiInfo(apiInfo())
                    .groupName("yichun123")
                    //配置是否启用Swagger，如果是false，在浏览器将无法访问，默认是true
                    .enable(true) 
                    .select()
                    //apis： 添加过滤条件,
                    .apis(RequestHandlerSelectors.basePackage("com.yichun.swagger_boot_demo.controller"))
                    //paths： 这里是控制哪些路径的api会被显示出来，比如下方的参数就是除了/user以外的其它路径都会生成api文档
                    .paths((String a) ->
                            !a.equals("/user"))
                    .build();
        }
    
        private ApiInfo apiInfo(){
            Contact contact = new Contact("名字：name", "个人链接：http://xxx.xxx.com/", "邮箱：XXX");
            return new ApiInfo(
                          "标题内容", // 标题
                          "描述内容", // 描述
                          "版本内容：v1.0", // 版本
                          "链接：http://terms.service.url/", // 组织链接
                           contact, // 联系人信息
                          "许可：Apach 2.0 ", // 许可
                          "许可链接：XXX", // 许可连接
                          new ArrayList<>()// 扩展
            );
        }
    }

1、分析

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQ0NTQzNTA4_size_16_color_FFFFFF_t_70 2]

2、RequestHandlerSelectors过滤

点进RequestHandlerSelectors源码，分析如下：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQ0NTQzNTA4_size_16_color_FFFFFF_t_70 3]

### 4.3、第一部分：配置API分组 ###

> 实际上，上面的内容就是一个完整的API组

1、配置一个分组  
我们之前说过，如果没有配置分组默认是default。通过Swagger实例Docket的`groupName()`方法即可配置分组，代码如下：

@Bean
    public Docket docket2(Environment environment) {
       return new Docket(DocumentationType.SWAGGER_2)
          .apiInfo(apiInfo()) // 配置基本API信息
          .groupName("hello") // 配置分组
           // 省略配置....
    }

2、如何配置多个分组  
很简单，配置多个分组只需要配置多个docket即可，代码如下：

@Bean
    public Docket docket1(){
       return new Docket(DocumentationType.SWAGGER_2)
          .groupName("组一")
          // 省略配置....
    }
    @Bean
    public Docket docket2(){
       return new Docket(DocumentationType.SWAGGER_2)
         .groupName("组二")
         // 省略配置....
    }
    @Bean
    public Docket docket3(){
       return new Docket(DocumentationType.SWAGGER_2)
         .groupName("组三")
         // 省略配置....
    }

### 4.4、Swagger2的常用注解 ###

讲第三部分和第四部分前，非常有必要先了解swagger2的常用注解，用注解的话，可以给一些比较难理解的属性或者接口，增加一些配置信息，让人更容易阅读！这点也是swagger2的重中之重！

首先我们得知道一点Swagger的所有注解定义在`io.swagger.annotations`包下。，这里只列出一些常用的注解，如下：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQ0NTQzNTA4_size_16_color_FFFFFF_t_70 4]  
如果要详细了解这些注解可以参考[swagger2 注解说明][swagger2]

### 4.5、第三部分：API请求列表 ###

请求接口列表：在组范围内，只要被Swagger2扫描匹配到的请求都会在这里出现。使用注解能更好的提高阅读性。  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQ0NTQzNTA4_size_16_color_FFFFFF_t_70 5]

### 4.6、第四部分：API实体列表 ###

之前说过，**只要实体在请求接口的返回值上（即使是泛型），都能映射到实体项中！是的，因此我们第一步是先有实体类。**

1、  
我们先随便创建一个实体类

@ApiModel("用户实体类")
    public class User {
        
        @ApiModelProperty("性别")
        public String sex;
    
        @ApiModelProperty(value ="用户名",allowableValues = "11,12")
        public int name;  
    }

当然`@ApiModelProperty`注解里有很多属性，也会有许多坑，这里注意一下，本篇文章暂不概述。

2、  
只要这个实体在请求接口的返回值上（包括泛型），都能映射到实体项中，所以我们编写代码如下：

@GetMapping("/User2")
     public User getUser2(){
     
        return new User();
     }

效果如下：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQ0NTQzNTA4_size_16_color_FFFFFF_t_70 6]

[SpringBoot_Springfox-Swagger2]: https://www.cnblogs.com/yichunguo/p/12665857.html
[1_Swagger]: https://www.cnblogs.com/yichunguo/p/12665857.html#1%E3%80%81swagger%E7%AE%80%E4%BB%8B
[2]: https://www.cnblogs.com/yichunguo/p/12665857.html#2%E3%80%81%E6%95%B4%E5%90%88%E5%89%8D%E5%8F%AF%E8%83%BD%E9%81%87%E5%88%B0%E7%9A%84%E9%97%AE%E9%A2%98
[3_SpringBoot_Swagger]: https://www.cnblogs.com/yichunguo/p/12665857.html#3%E3%80%81springboot%E9%9B%86%E6%88%90swagger
[4_Swagger]: https://www.cnblogs.com/yichunguo/p/12665857.html#4%E3%80%81%E9%85%8D%E7%BD%AEswagger
[4.1_Swagger]: https://www.cnblogs.com/yichunguo/p/12665857.html#41%E3%80%81swagger%E5%9B%9B%E9%83%A8%E5%88%86%E5%B8%83%E5%B1%80
[4.2_API]: https://www.cnblogs.com/yichunguo/p/12665857.html#42%E3%80%81%E7%AC%AC%E4%BA%8C%E9%83%A8%E5%88%86%EF%BC%9Aapi%E5%9F%BA%E6%9C%AC%E4%BF%A1%E6%81%AF
[1]: https://www.cnblogs.com/yichunguo/p/12665857.html#1%E3%80%81%E5%88%86%E6%9E%90
[2_RequestHandlerSelectors]: https://www.cnblogs.com/yichunguo/p/12665857.html#2%E3%80%81requesthandlerselectors%E8%BF%87%E6%BB%A4
[4.3_API]: https://www.cnblogs.com/yichunguo/p/12665857.html#43%E3%80%81%E7%AC%AC%E4%B8%80%E9%83%A8%E5%88%86%EF%BC%9A%E9%85%8D%E7%BD%AEapi%E5%88%86%E7%BB%84
[4.4_Swagger2]: https://www.cnblogs.com/yichunguo/p/12665857.html#44%E3%80%81swagger2%E7%9A%84%E5%B8%B8%E7%94%A8%E6%B3%A8%E8%A7%A3
[4.5_API]: https://www.cnblogs.com/yichunguo/p/12665857.html#45%E3%80%81%E7%AC%AC%E4%B8%89%E9%83%A8%E5%88%86%EF%BC%9Aapi%E8%AF%B7%E6%B1%82%E5%88%97%E8%A1%A8
[4.6_API]: https://www.cnblogs.com/yichunguo/p/12665857.html#46%E3%80%81%E7%AC%AC%E5%9B%9B%E9%83%A8%E5%88%86%EF%BC%9Aapi%E5%AE%9E%E4%BD%93%E5%88%97%E8%A1%A8
[Intellij IDEA Cannot Resolve Symbol XXX]: https://blog.csdn.net/qq_44543508/article/details/105378816
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQ0NTQzNTA4_size_16_color_FFFFFF_t_70]: /images/20221119/03a9056ea96749839372c7c1db5e6c97.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQ0NTQzNTA4_size_16_color_FFFFFF_t_70 1]: https://img-blog.csdnimg.cn/20200409060943341.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQ0NTQzNTA4,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQ0NTQzNTA4_size_16_color_FFFFFF_t_70 2]: https://img-blog.csdnimg.cn/20200409095728658.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQ0NTQzNTA4,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQ0NTQzNTA4_size_16_color_FFFFFF_t_70 3]: https://img-blog.csdnimg.cn/20200409101303608.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQ0NTQzNTA4,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQ0NTQzNTA4_size_16_color_FFFFFF_t_70 4]: https://img-blog.csdnimg.cn/202004091045286.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQ0NTQzNTA4,size_16,color_FFFFFF,t_70
[swagger2]: https://blog.csdn.net/xiaojin21cen/article/details/78654652?depth_1-utm_source=distribute.pc_relevant.none-task-blog-BlogCommendFromBaidu-2&utm_source=distribute.pc_relevant.none-task-blog-BlogCommendFromBaidu-2
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQ0NTQzNTA4_size_16_color_FFFFFF_t_70 5]: https://img-blog.csdnimg.cn/20200409111057180.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQ0NTQzNTA4,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQ0NTQzNTA4_size_16_color_FFFFFF_t_70 6]: https://img-blog.csdnimg.cn/20200409112802271.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQ0NTQzNTA4,size_16,color_FFFFFF,t_70