SpringBoot框架集成Swagger

集成Swagger

学习目标：

• 了解Swagger的概念及作用
• 掌握在项目中集成Swagger自动生成API文档

1、Swagger简介

前后端分离

• 前端 -> 前端控制层、视图层
• 后端 -> 后端控制层、服务层、数据访问层
• 前后端通过API进行交互
• 前后端相对独立且松耦合

产生的问题

• 前后端集成，前端或者后端无法做到“及时协商，尽早解决”，最终导致问题集中爆发

解决方案

• 首先定义schema [ 计划的提纲 ]，并实时跟踪最新的API，降低集成风险

Swagger

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

2、SpringBoot集成

SpringBoot集成Swagger => springfox，两个jar包

• Springfox-swagger2
• swagger-springmvc

使用Swagger

要求：jdk 1.8 + 否则swagger2无法运行

步骤：

1. 新建一个SpringBoot-web项目

2. 添加Maven依赖,在maven中搜springfox-swagger

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

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

或者只导入一个启动器

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

3. 编写HelloController，测试确保运行成功！

4. 要使用Swagger，我们需要编写一个配置类-SwaggerConfifig来配置 Swagger

2.x版本

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

3.x版本,Springfox 3.x 删除了对 guava 和其他 3rd 方库的依赖（还不是零依赖！依赖于 spring 插件和用于注解和模型的开放 api 库）所以如果你使用了 guava 依赖，这些将需要转换到 java 8 函数接口

package com.itheibai.config;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2 
@EnableWebMvc //不写会报错，也可以写在启动器类上
public class SwaggerConfig {
}

5. 访问测试 ：http://localhost:8080/swagger-ui.html ，3.x版本地址：http://localhost:8080/swagger-ui/index.html 可以看到swagger的界面；

注：2.x升级到3.x 参考https://springfox.github.io/springfox/docs/snapshot/

3、配置Swagger

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

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

2. 可以通过apiInfo()属性配置文档信息

//配置文档信息
private ApiInfo apiInfo() {
    Contact contact = new Contact("itheibai", "https://www.itheibai.com", "itheibai@qq.com");
    return new ApiInfo(
            "Swagger学习",
            "学习如何配置Swagger",
            "v1.0",
            "http://terms.service.url/组织链接", // 组织链接
            contact, // 联系人信息
            "Apach 2.0 许可", // 许可 "许可链接",
            "http://www.apache.org/licenses/LICENSE-2.0",// 许可连接
            new ArrayList<>()// 扩展
    );
}

3. Docket 实例关联上 apiInfo() 

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

4. 重启项目，访问测试 http://localhost:8080/swagger-ui.html 看下效果；3.x访问http://localhost:8080/swagger-ui/index.html#/

4、配置扫描接口

1. 构建Docket时通过select()方法配置怎么扫描接口。

@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
            .select() //通过.select()方法，去配置扫描接口，RequestHandlerSelectors配置如何扫描接口
            .apis(RequestHandlerSelectors.basePackage("com.itheibai.controller"))
            .build();
}

2. 重启项目测试，由于我们配置根据包的路径扫描接口，所以我们只能看到一个类

3. 除了通过包路径配置扫描接口外，还可以通过配置其他方式扫描接口，这里注释一下所有的配置方

式：

any() // 扫描所有，项目中的所有接口都会被扫描到
none() // 不扫描接口
// 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
withMethodAnnotation(final Class<? extends Annotation> annotation)
// 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有
controller注解的类中的接口
withClassAnnotation(final Class<? extends Annotation> annotation)
basePackage(final String basePackage) // 根据包路径扫描接口

4. 除此之外，我们还可以配置接口扫描过滤：

@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
            .select() //通过.select()方法，去配置扫描接口，RequestHandlerSelectors配置如何扫描接口
            .apis(RequestHandlerSelectors.basePackage("com.itheibai.controller"))
            //配置如何通过path过滤，即这里只扫描请求以/itheibai开头的接口
            .paths(PathSelectors.ant("/itheibai/**"))
            .build();
}

5. 这里的可选值还有 

any() // 任何请求都扫描
none() // 任何请求都不扫描
regex(final String pathRegex) // 通过正则表达式控制
ant(final String antPattern) // 通过ant()控制

5、配置开关Swagger

1. 通过enable()方法配置是否启用swagger，如果是false，swagger将不能在浏览器中访问了 

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

2. 如何动态配置当项目处于test、dev环境时显示swagger，处于prod时不显示？ 

@Bean
public Docket docket(Environment environment) {
    //设置要显示swagger的环境
    Profiles of = Profiles.of("dev","test");
    //判断当前是否处于该环境
    //通过 enable() 接收此参数判断是否要显示
    boolean b = environment.acceptsProfiles(of);
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
            .enable(b) //配置是否启用Swagger，如果是false,在浏览器将无法访问
            .select() //通过.select()方法，去配置扫描接口，RequestHandlerSelectors配置如何扫描接口
            .apis(RequestHandlerSelectors.basePackage("com.itheibai.controller"))
            //配置如何通过path过滤，即这里只扫描请求以/itheibai开头的接口
            .paths(PathSelectors.ant("/**"))
            .build();
}

3. 可以在项目中增加一个dev的配置文件查看效果！

application.yml

spring:
  profiles:
    active: test
server:
  port: 8080 #默认端口号
---
spring:
  datasource:
    username: root
    password: 123456
    #?serverTimezone=UTC解决时区的报错
    url: jdbc:mysql://localhost:3306/springboot?serverTimezone=UTC&useUnicode=true&characterEncoding=utf-8
    driver-class-name: com.mysql.cj.jdbc.Driver
    type: com.alibaba.druid.pool.DruidDataSource #自定义数据源
    #SpringBoot 默认配置是不注入这些属性值的，需要自己绑定
    #druid 数据源专有配置
    druid:
      initialSize: 5
      minIdle: 5
      maxActive: 20
      maxWait: 60000
      minEvictableIdleTimeMillis: 300000
      validationQuery: SELECT 1 FROM DUAL
      testWhileIdle: true
      testOnBorrow: false
      testOnReturn: false
      poolPreparedStatements: true

      #配置监控统计拦截的filters，stat:监控统计、log4j：日志记录、wall：防御sql注入
      #如果允许时报错 java.lang.ClassNotFoundException: org.apache.log4j.Priority
      #则导入 log4j 依赖即可，Maven 地址： https://mvnrepository.com/artifact/log4j/log4j
      filters: stat,wall,log4j
      maxPoolPreparedStatementPerConnectionSize: 20
      useGlobalDataSourceStat: true
      connectionProperties: druid.stat.mergeSql=true;druid.stat.slowSqlMillis=500
  config:
    activate:
      on-profile: "test" #配置环境的名称
mybatis:
  mapper-locations: classpath:mybatis/mapper/*.xml #映射文件路径
  type-aliases-package: com.itheibai.pojo #实体类别名包路径
  configuration:
    map-underscore-to-camel-case: true #开启驼峰命名
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl #控制台输出执行sql
#配置日志级别
logging:
  level:
    com.itheibai: debug
    org.springframework: info
---
spring:
  config:
    activate:
      on-profile: dev #配置环境的名称
server:
  port: 8081
---
spring:
  config:
    activate:
      on-profile: prod #配置环境的名称
server:
  port: 8082

6、配置API分组

1. 如果没有配置分组，默认是default。通过groupName()方法即可配置分组： 

@Bean
public Docket docket(Environment environment) {
    //设置要显示swagger的环境
    Profiles of = Profiles.of("dev","test");
    //判断当前是否处于该环境
    //通过 enable() 接收此参数判断是否要显示
    boolean b = environment.acceptsProfiles(of);
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
            .enable(b) //配置是否启用Swagger，如果是false,在浏览器将无法访问
            .groupName("itheibai") //配置分组名称
            .select() //通过.select()方法，去配置扫描接口，RequestHandlerSelectors配置如何扫描接口
            .apis(RequestHandlerSelectors.basePackage("com.itheibai.controller"))
            //配置如何通过path过滤，即这里只扫描请求以/itheibai开头的接口
            .paths(PathSelectors.ant("/**"))
            .build();
}

2. 重启项目查看分组

3. 如何配置多个分组？配置多个分组只需要配置多个docket即可：

 @Bean
public Docket docket1() {
    return new Docket(DocumentationType.SWAGGER_2).groupName("分组1");
}
@Bean
public Docket docket2() {
    return new Docket(DocumentationType.SWAGGER_2).groupName("分组2");
}
@Bean
public Docket docket3() {
    return new Docket(DocumentationType.SWAGGER_2).groupName("分组3");
}

4. 重启项目查看

7、实体配置

1. 新建一个实体类

package com.itheibai.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
@ApiModel("部门实体类信息")
@Data //get、set方法
@NoArgsConstructor //无参构造函数
@AllArgsConstructor //所有带参构造函数
public class Department {
    @ApiModelProperty("部门id")
    private Integer id;
    @ApiModelProperty("部门名称")
    private String departmentName;
}

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

//查询全部部门
@GetMapping("/getDepartments")
public List<Department> getDepartments(){
    return departmentMapper.getDepartments();
}

3. 重启查看测试

注：并不是因为@ApiModel这个注解让实体显示在这里了，而是只要出现在接口方法的返回值上的实体

都会显示在这里，而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的。

@ApiModel为类添加注释

@ApiModelProperty为类属性添加注释

8、常用注解

Swagger的所有注解定义在io.swagger.annotations包下

下面列一些经常用到的，未列举出来的可以另行查阅说明： 

我们也可以给请求的接口配置一些注释 

package com.itheibai.controller;
import com.itheibai.mapper.DepartmentMapper;
import com.itheibai.pojo.Department;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.bind.annotation.RestController;
import java.util.List;
@RestControllererewoppoi-tredcxzgvbbvc             ，  0
@Api(tags = "部门控制类") //类名注释
public class DepartmentController {
    @Autowired
    DepartmentMapper departmentMapper;
    //查询全部部门
    @ApiOperation(value = "查询所有部门信息",httpMethod = "GET") //方法注释
    @GetMapping("/getDepartments")
    public List<Department> getDepartments(){
        return departmentMapper.getDepartments();
    }
    //根据id查询部门
    @GetMapping("/getDepartment/{id}")
    public Department getDepartment(@ApiParam("部门id")@PathVariable("id")Integer id){
        return departmentMapper.getDepartment(id);
    }
}

这样的话，可以给一些比较难理解的属性或者接口，增加一些配置信息，让人更容易阅读！

相较于传统的Postman或Curl方式测试接口，使用swagger简直就是傻瓜式操作，不需要额外说明文档

(写得好本身就是文档)而且更不容易出错，只需要录入数据然后点击Execute，如果再配合自动化框架，

可以说基本就不需要人为操作了。 

Swagger是个优秀的工具，现在国内已经有很多的中小型互联网公司都在使用它，相较于传统的要先出

Word接口文档再测试的方式，显然这样也更符合现在的快速迭代开发行情。当然了，提醒下大家在正式

环境要记得关闭Swagger，一来出于安全考虑二来也可以节省运行时内存。