在实习接触第一个公司项目时，就已经见识过了项目中的Swagger注解。但对其并不了解，甚至是干什么的都不知道，今天对其学习了一下，在此简单记录一下Swagger在多Model项目中是如何整合使用的。
一、Swagger介绍
前后端分离开发模式中，api文档是最好的沟通方式。
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
1.及时性 (接口变更后，能够及时准确地通知相关前后端开发人员)
2.规范性 (并且保证接口的规范性，如接口的地址，请求方式，参数及响应格式和错误信息)
3.一致性 (接口信息一致，不会出现因开发人员拿到的文档版本不一致，而出现分歧)
4.可测性 (直接在接口文档上进行测试，以方便理解业务)
在日常写接口过程中，有些接口是无法直接在浏览器中进行测试，这时候我们就可以采用接口测试工具。
在我所了解的接口测试工具中，常用的应该就是postman和Swagger了。但是对于后端开发人员来说，更倾向于使用Swagger。
二、整合Swagger
以我的多Model项目为例
在顶级父工程下创建common模块，并在其pom.xml文件中引入Swagger依赖
<!--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>
引入依赖后在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
<dependency>
<groupId>com.atguigu</groupId>
<artifactId>service_base</artifactId>
<version>0.0.1-SNAPSHOT</version>
</dependency>
在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<EduTeacher> 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进行接口测试整合方法的简单介绍。
网友评论