前言
以前刚刚学Java的时候,写完接口和实现后,都没有测试的习惯,如果是前后端分离的项目,我们写后端服务的人把一个没有经过任何测试的接口给到前端,别人会非常抓狂。因为接口是前端和后端产生交互的地方,如果我们后端写完的接口有问题,而直接给别人,会很浪费时间。因此,后端每开发完一个接口,都非常有必要自己先测试,测试OK后再将接口文档提供给前端人员,最后进行前后端联调。需要一个非常快捷方便的工具来帮助后端进行接口测试,刚好接触到了Swagger,对它有了一个大概的了解。
1、Swagger是什么
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。
2、Swagger的作用
- 接口的文档在线自动生成。
- 接口功能的测试。
3、Swagger的基本使用
(1)pom依赖
<!-- 引入swagger2依赖 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- swagger-ui依赖 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
(2)Swagger配置类
我这里将api单独作为一个工程独立出去了,所有的api都由这个工程管理。该工程的config包下有一个配置类,如下:
package com.ycz.api.config;
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.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/*
* Swagger配置类
*/
@Configuration
@EnableSwagger2
public class Swagger2Config {
//注册Docket
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2).
apiInfo(apiInfo()).
select().
apis(RequestHandlerSelectors.basePackage("com.ycz")).
paths(PathSelectors.any()).
build();
}
//定义Api文档
private ApiInfo apiInfo() {
return new ApiInfoBuilder().
title("个人信息api文档").
description("个人信息api文档").
version("1.0").
build();
}
}
(3)Api
package com.ycz.api.person;
import com.ycz.domain.others.QueryResponseResult;
import com.ycz.domain.others.ResponseResult;
import com.ycz.domain.person.Person;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
@Api(value = "个人信息管理",description = "提供个人的增删改查",tags = {"个人增删改查"})
public interface PersonControllerApi {
@ApiOperation("按照地址查询个人信息")
QueryResponseResult<Person> findPersonsByAddress(String address);
@ApiOperation("添加记录")
ResponseResult addPerson(Person person);
@ApiOperation("修改记录")
ResponseResult updatePerson(Person person);
@ApiOperation("删除记录")
ResponseResult delPerson(Integer id);
@ApiOperation("分页查询")
QueryResponseResult<Person> queryPersonsPaged(int page,int size);
}
(4)controller
我这里每个controller直接实现了api,接口在这里暴露出来,如下:
package com.ycz.swagger.controller;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import com.ycz.api.person.PersonControllerApi;
import com.ycz.domain.others.QueryResponseResult;
import com.ycz.domain.others.ResponseResult;
import com.ycz.domain.person.Person;
import com.ycz.swagger.service.PersonService;
@RestController
@RequestMapping("/person")
public class PersonController implements PersonControllerApi{
@Autowired
PersonService personService;
@Override
@GetMapping("/list/{address}")
public QueryResponseResult<Person> findPersonsByAddress(@PathVariable("address") String address) {
return personService.findByAddress(address);
}
@Override
@PostMapping("/savePerson")
public ResponseResult addPerson(@RequestBody Person person) {
return personService.addPerson(person);
}
@Override
@PutMapping("/updatePerson")
public ResponseResult updatePerson(@RequestBody Person person) {
return personService.updatePerson(person);
}
@Override
@DeleteMapping("/delPerson/{id}")
public ResponseResult delPerson(@PathVariable("id") Integer id) {
return personService.delPerson(id);
}
@Override
@GetMapping("/list/{page}/{size}")
public QueryResponseResult<Person> queryPersonsPaged(@PathVariable("page")int page,
@PathVariable("size")int size) {
return personService.queryPersonsPaged(page,size);
}
}
service和dao这里就不贴出来了,重点是研究Swagger。
(5)效果
启动springboot工程,我的接口是定的10000,启动工程后打开浏览器,
输入:http://localhost:10000/swagger-ui.html
注意是端口后直接加swagger-ui.html,固定格式。效果如下:
(6)测试
选择要进行测试的接口,这里我测一下查询,如下:
点击execute执行,返回结果如下:
返回类型是自定义的封装类型,这个接口的测试就OK了,没问题之后就可以导出形成文档交给前端人员了。