SpringBoot整合Swagger2

前后端分离后，维护接口文档基本上是必不可少的工作。一个理想的状态是设计好后，接口文档发给前端和后端，大伙按照既定的规则各自开发，开发好了对接上了就可以上线了。当然这是一种非常理想的状态，实际开发中却很少遇到这样的情况，接口总是在不断的变化之中，有变化就要去维护，做过的小伙伴都知道这件事有多么头大！还好，有一些工具可以减轻我们的工作量，Swagger2就是其中之一，至于其他类似功能但是却收费的软件，这里就不做过多介绍了。本文主要和大伙来聊下在Spring Boot中如何整合Swagger2。

1、Swagger简介

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

2.SpringBoot集成Swagger

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

2.1导入两个依赖

当然，首先是创建一个Spring Boot项目，加入web依赖，创建成功后，加入两个Swagger2相关的依赖，完整的依赖如下：

<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>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

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

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

}

2.3这个时候已经算是初步整合完毕了，启动项目可访问http://localhost:8080/swagger-ui.html 可以看到swagger的界面，如下：

3.配置Swagger

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

3.1Swagger四部分布局

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

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

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

3.2 第二部分：API基本信息

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

/**
 * Swagger2配置类
 * @Configuration：说明这是一个配置类
 * @EnableSwagger2：该注解开启Swagger2的自动配置
 * @author qzz
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
   

    @Bean
    public Docket createRestAPi(){
   

        //构造函数传入初始化规范，这是swagger2规范
        return new Docket(DocumentationType.SWAGGER_2)
                //apiInfo：添加api的详情信息，参数为ApiInfo类型的参数，这个参数包含了基本描述信息：比如标题、描述、版本之类的，开发中一般都是自定义这些信息
                .apiInfo(apiInfo())
                // select、apis、paths、build 这四个是一组的，组合使用才能返回一个Docket实例对象，其中apis和paths是可选的。
                .select()
                //apis:添加过滤条件。RequestHandlerSelectors中有很多过滤方式；RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)：加了ApiOperation注解的类，生成接口文档
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                //paths：控制那些路径的api会被显示出来。
                .paths(PathSelectors.any())
                .