一、Swagger2 介绍

在前后端分离开发模式中，API文档是最好的沟通方式。

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

Swagger 能够生成一个在线的接口文档，可以看到文档中的接口有什么功能、里面需要传递哪些参数、返回的数据。方便测试接口。

特点：

1、及时性（接口变更后，能够及时准确地通知相关前后端开发人员）

2、规范性（保证接口的规范性，如接口的地址、请求方式、参数及响应格式和错误信息）

3、一致性（接口信息一致，不会出现因开发人员拿到的文档版本不一致，而出现分歧）

4、可测性（直接在接口文档上进行测试，以方便理解业务）

二、配置 Swagger2

由于项目中有很多个模块，每个模块都可能需要 Swagger 测试，因此可以创建一个公共的模块，把 Swagger 配置在这个公共模块中，哪个模块需要用到 Swagger 测试，就引入Swagger 即可。

1、在父模块中创建一个公共的子模块

2、在 pom.xml 文件中引入需要的坐标

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <parent>
        <artifactId>guli_parent</artifactId>
        <groupId>cn.henu</groupId>
        <version>0.0.1-SNAPSHOT</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>

    <artifactId>common</artifactId>
    <packaging>pom</packaging>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
            <scope>provided </scope>
        </dependency>

        <!--mybatis-plus-->
        <dependency>
            <groupId>com.baomidou</groupId>
            <artifactId>mybatis-plus-boot-starter</artifactId>
            <scope>provided </scope>
        </dependency>

        <!--lombok用来简化实体类：需要安装lombok插件-->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <scope>provided </scope>
        </dependency>

        <!--swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <scope>provided </scope>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <scope>provided </scope>
        </dependency>

        <!-- redis -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-redis</artifactId>
        </dependency>

        <!-- spring2.X集成redis所需common-pool2
        <dependency>
            <groupId>org.apache.commons</groupId>
            <artifactId>commons-pool2</artifactId>
            <version>2.6.0</version>
        </dependency>-->
    </dependencies>

</project>

3、删除 common 模块下的 src 目录，因为不需要在 src 目录下写代码。

4、在 common 模块下再创建一个子模块 service_base，把 Swagger 配置在 service_base 模块下。

5、 在 service_base 模块中创建一个配置类，用于配置 Swagger

5-1、首先创建一个包（注意这个包名要和下面的 service 中的子模块的包名相同）

5-2、编写配置类 SwaggerConfig（不需要自己写，复制粘贴就行）

package cn.henu.servicebase;

import com.google.common.base.Predicates;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
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;

@Configuration//表示这是一个配置类
@EnableSwagger2//表示这是一个Swagger类，整合Swagger
public class SwaggerConfig {

    //访问地址：http://localhost:8001/swagger-ui.html

    //Swagger插件
    @Bean
    public Docket webApiConfig(){

        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi")//("webApi")是自己命名的，写abc也可以
                .apiInfo(webApiInfo())
                .select()
                .paths(Predicates.not(PathSelectors.regex("/admin/.*")))
                .paths(Predicates.not(PathSelectors.regex("/error.*")))
                .build();

    }

    private ApiInfo webApiInfo(){

        return new ApiInfoBuilder()
                .title("网站-课程中心API文档")
                .description("本文档描述了课程中心微服务接口定义")
                .version("1.0")
                .contact(new Contact("java", "http://atguigu.com", "123456@qq.com"))
                .build();
    }
}

注意：Swagger 在 common 模块中，在 service_edu 模块中要想使用 Swagger，需要下面几步：

6、在 service 模块的 pom.xml 文件中引入 service_base 的依赖

<dependency>
    <groupId>cn.henu</groupId>
    <artifactId>service_base</artifactId>
    <version>0.0.1-SNAPSHOT</version>
</dependency>

7、由于 SwaggerConfig 是一个配置类，在项目启动的时候要加载配置类，但是 SwaggerConfig 所在的模块不在 service_edu 中，在项目启动时不会启动 SwaggerConfig，需要在启动类上加上一个注解@ComponentScan(basePackages = {"cn.henu"})，设置包的扫描规则

8、启动项目，打开浏览器输入 http://localhost:8001/swagger-ui.html（这个地址是固定地址，前面是项目的IP和端口号，后面加上swagger-ui.html）

展开 controller，里面有两个接口，一个是查询所有讲师（get请求），一个是删除讲师数据（delete请求）

上面两个接口对应下面的 Controller 代码

package cn.henu.eduservice.controller;


import cn.henu.eduservice.domain.EduTeacher;
import cn.henu.eduservice.service.EduTeacherService;
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.*;

import java.util.List;

/**
 * <p>
 * 讲师 前端控制器
 * </p>
 *
 * @author testjava
 * @since 2021-02-10
 */
//@RestController注解包含@Controller注解和@ResponseBody注解
@RestController//将这个Controller交给Spring管理，返回的数据都是json数据
@RequestMapping("/eduservice/teacher")
public class EduTeacherController {

    //访问地址：http://localhost:8001/eduservice/teacher/findAll
    //把service注入
    @Autowired
    private EduTeacherService teacherService;

    //1、查询讲师表所有数据
    //rest风格
    @GetMapping("findAll")//查询用@GetMapping
    public List<EduTeacher> findAllTeacher(){
        //调用service的方法实现查询所有的操作
        List<EduTeacher> list = teacherService.list(null);
        return list;
    }

    //2、逻辑删除讲师
    @DeleteMapping("{id}")//删除用@DeleteMapping，("{id}")表示需要根据id值进行删除，这个id值需要通过浏览器地址栏传递，在下面的@PathVariable注解进行接收
    public boolean removeTeacher(@PathVariable String id){//@PathVariable 获取路径中id的值
        boolean flag = teacherService.removeById(id);
        return flag;
    }
}

展开第一个请求，点击 Try it out!

展开第二个请求，输入要删除的讲师的id值，然后点击 Try it out!

数据库中表的数据：

输入1，然后点击Try it out!

再看数据库中的id为1的数据的is_deleted字段的值时候由0变为1

添加一些注解，让文档看起来更清晰

package cn.henu.eduservice.controller;


import cn.henu.eduservice.domain.EduTeacher;
import cn.henu.eduservice.service.EduTeacherService;
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.*;

import java.util.List;

/**
 * <p>
 * 讲师 前端控制器
 * </p>
 *
 * @author testjava
 * @since 2021-02-10
 */
@Api(description="讲师管理")//这个注解只为了在Swagger测试文档上显示中文注释，有助于查看
//@RestController注解包含@Controller注解和@ResponseBody注解
@RestController//将这个Controller交给Spring管理，返回的数据都是json数据
@RequestMapping("/eduservice/teacher")
public class EduTeacherController {

    //访问地址：http://localhost:8001/eduservice/teacher/findAll
    //把service注入
    @Autowired
    private EduTeacherService teacherService;

    //1、查询讲师表所有数据
    //rest风格
    @ApiOperation(value = "查询所有讲师列表")//这个注解只为了在Swagger测试文档上显示中文注释，有助于查看
    @GetMapping("findAll")//查询用@GetMapping
    public List<EduTeacher> findAllTeacher(){
        //调用service的方法实现查询所有的操作
        List<EduTeacher> list = teacherService.list(null);
        return list;
    }

    //2、逻辑删除讲师
    @ApiOperation(value = "逻辑删除讲师(根据ID删除讲师)")//这个注解只为了在Swagger测试文档上显示中文注释，有助于查看
    @DeleteMapping("{id}")//删除用@DeleteMapping，("{id}")表示需要根据id值进行删除，这个id值需要通过浏览器地址栏传递，在下面的@PathVariable注解进行接收
    public boolean removeTeacher(@ApiParam(name = "id", value = "讲师ID", required = true)//这个注解只为了在Swagger测试文档上显示中文注释，有助于查看
                                     @PathVariable String id){//@PathVariable 获取路径中id的值
        boolean flag = teacherService.removeById(id);
        return flag;
    }
}

再运行，看文档中的提示