多Model项目中，使用Swagger

在实习接触第一个公司项目时，就已经见识过了项目中的Swagger注解。但对其并不了解，甚至是干什么的都不知道，今天对其学习了一下，在此简单记录一下Swagger在多Model项目中是如何整合使用的。

一、Swagger介绍

前后端分离开发模式中，api文档是最好的沟通方式。
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
1.及时性 (接口变更后，能够及时准确地通知相关前后端开发人员)
2.规范性 (并且保证接口的规范性，如接口的地址，请求方式，参数及响应格式和错误信息)
3.一致性 (接口信息一致，不会出现因开发人员拿到的文档版本不一致，而出现分歧)
4.可测性 (直接在接口文档上进行测试，以方便理解业务)

在日常写接口过程中，有些接口是无法直接在浏览器中进行测试，这时候我们就可以采用接口测试工具。
在我所了解的接口测试工具中，常用的应该就是postman和Swagger了。但是对于后端开发人员来说，更倾向于使用Swagger。

二、整合Swagger

以我的多Model项目为例
在顶级父工程下创建common模块，并在其pom.xml文件中引入Swagger依赖

        
            io.springfox
            springfox-swagger2
            provided 
        

        
            io.springfox
            springfox-swagger-ui
            provided 
        

引入依赖后在common模块下再创建common_base模块并创建Swagger配置类

image.png

Swagger配置类：

package com.atguigu.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;

/**
 * @Author su mingxin
 * @Date 2020/9/16 14:38
 *swagger：
 * 1.生成一个在线文档，文档中有我们已经定义的接口
 * 2.对我们已经定义的接口进行测试
 */
@Configuration//配置类
@EnableSwagger2//swagger注解
public class SwaggerConfig {

    @Bean
    public Docket webApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi")
                .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("mingxin Su", "http://atguigu.com", "*******@qq.com"))
                .build();
    }
}

这样Swagger大致就配置好了，接下来，就往接口模块进行引入。

三、在功能接口中引入Swagger

在模块service模块引入service_base

            com.atguigu
            service_base
            0.0.1-SNAPSHOT
        

在service的子模块——service_edu模块的启动类中添加@ComponentScan注解

image.png

这样，我们便可以对功能接口通过Swagger进行测试了。
我们也可以进行一些自定义设置

/**
 * @author testjava
 * @since 2020-09-16
 *
 * 定义在类上：@Api
 * 定义在方法上：@ApiOperation  这三个注解用来丰富swagger的提示信息
 * 定义在参数上：@ApiParam
 */
@Api(description = "讲师管理")
@RestController
@RequestMapping("/eduservice/teacher")
public class EduTeacherController {

    @Autowired
    private EduTeacherService teacherService;

    //查询所有讲师信息
    @ApiOperation("查询讲师列表")
    @GetMapping("findAll")
    public R findAllTeacher(){
        List list = teacherService.list(null);
//        int a = 1/0; 测试全局异常处理功能
        return R.ok().data("items",list);
    }

    //逻辑删除讲师
    @ApiOperation("根据id(逻辑)删除讲师")
    @DeleteMapping("{id}")
    public R removeTeacher(@ApiParam(name = "id", value = "讲师ID", required = true) @PathVariable String id){
        boolean flag = teacherService.removeById(id);
        if (flag){
            return R.ok();
        }else {
            return R.error();
        }
    }
}

四、使用Swagger

1.启动你的项目
2.访问路径http://localhost:你的端口号/swagger-ui.html

image.png

3.进行测试

image.png

这里我用查询讲师列表为例

image.png

image.png

image.png

image.png

以上就是使用Swagger进行接口测试整合方法的简单介绍。