参考链接：5分钟学会swagger配置
参考视频：Swagger-前后端分离开发的API接口框架
一、背景
现在的网站大多都是前后端分离式的开发，前后端都衍生出了自己的框架。现在前后端交互的唯一方式就是API接口。
曾经前后端交互都需要后端人员手动编写API接口文档，规定路径、请求方式、返回类型，这样效率很低。
swagger就是更好地书写API文档的框架。
二、swagger介绍
swagger可以根据后台接口自动生成可视化的restful风格的API文档，并可以进行API测试（发送各种请求，测试接口）
1、前端人员不用再去理解后端代码，后端人员也不用专门编写接口文档。
2、swagger直接自动生成可供测试、可视化的API文档，前端人员在不知道后端代码的情况下，也能根据swagger提供的API文档理解每个接口的作用，并可以测试接口是否能够正常使用。
三、在maven+springboot项目中使用swagger
- 首先在pom.xml中导入依赖
springfox-swagger2是swagger的java实现
springfox-swagger-ui是网页上显示swagger文档的jar包
<!--swagger jar包-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>
<!--swagger jar包-->
- 编写swagger配置文件
创建一个config文件夹，在文件夹里创建SwaggerConfig.java文件作为我们的swagger配置文件。
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
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注解
@ComponentScan("whu.xsy.swagger_use.controller")//扫描控制器包下的文件
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo());
}
//展现API文档的基本信息
private ApiInfo apiInfo(){
//联系人信息(展现在主页)
Contact contact = new Contact("xsy",
"","827041735@qq.com");
return new ApiInfoBuilder()
.title("测试swagger")
.description("测试swagger对于接口的展示和调用")
.contact(contact)
.version("1.1.0")
.build();
}
}
- 创建实体类student
| 注解 | 作用 |
|---|---|
| @ApiModel | 标注在实体类上,value=类名描述 |
| @ApiModelProperty | 标注在属性上，value=字段描述，required默认为false，如果是不可缺少的字段，比如主键，required则要变成true |
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
@ApiModel(value = "学生类")
public class student {
@ApiModelProperty(value = "学号",required = true)
private int id;
@ApiModelProperty(value = "姓名")
private String name;
public student() {}
public student(int id, String name) {
this.id = id;
this.name = name;
}
public int getId() { return id; }
public void setId(int id) { this.id = id; }
public String getName() { return name; }
public void setName(String name) { this.name = name; }
}
- 创建控制器studentController（此处用List模拟数据库）
| 注解 | 作用 |
|---|---|
| @Api | 标注在类上，tags则为类的名字，会展示给前端 |
| @ApiOperation | 标注在方法上，value简单地概括方法的用处，notes则描述方法的使用 |
| @ApiImplicitParam | 标注在方法上，用于描述参数字段，name是参数的名字（一定要与@Requestparam、@PathVariable、或者传递的类中的字段名相同，否则会在前端显示新的参数），required默认为false，如果是不可缺少的字段，则要改为true |
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
import whu.xsy.swagger_use.entity.student;
import java.util.ArrayList;
import java.util.List;
@RestController
@RequestMapping("/student")
@Api(value = "studentController", tags = "学生模块") //标注在类上的
public class studentController {
//模拟数据库
private static List<student> students = new ArrayList<>();
//初始化模拟数据库
static{
students.add(new student(1,"xsy"));
students.add(new student(2,"theory"));
}
@ApiOperation(
value = "获取所有学生信息",
notes = "获取所有学生的学号和姓名"
)
@GetMapping("")
public List<student> getAll(){
return students;
}
@ApiOperation(
value = "获取单个学生",
notes = "根据id查询学生，id为整数，返回学生实体，没查到则返回null"
)
@ApiImplicitParam(value = "学生学号", name = "id",paramType = "path")
@GetMapping("/{id}")
public student getById(@PathVariable("id") int id){
for (student s : students) {
if(s.getId() == id)
return s;
}
return null;
}
@ApiOperation(
value = "添加单个学生",
notes = "前端上传学生信息（学号，姓名）"
)
//此处 name 一定要与student中的变量名相同，否则在前端会生成新的parameter
@ApiImplicitParams({
@ApiImplicitParam(value = "学生学号",name = "id",paramType = "query"),
@ApiImplicitParam(value = "学生姓名",name = "name",paramType = "query")
})
@PostMapping("")
public boolean add(student student){
return students.add(student);
}
@ApiOperation(
value = "更新单个学生",
notes = "前端上传学生信息（学号，姓名），学号相同则会更新"
)
//此处 name 一定要与student中的变量名相同，否则在前端会生成新的parameter
@ApiImplicitParams({
@ApiImplicitParam(value = "学生学号",name = "id",paramType = "query"),
@ApiImplicitParam(value = "学生姓名",name = "name",paramType = "query")
})
@PutMapping("")
public boolean update(student student){
for (student s : students) {
if(s.getId() == student.getId()) {
students.set(students.indexOf(s), student);
return true;
}
}
return false;
}
@ApiOperation(
value = "删除单个学生",
notes = "根据学生id删除某个学生"
)
@ApiImplicitParam(value = "学生学号", name = "id",paramType = "path")
@DeleteMapping(value = "/{id}")
public boolean deleteById(@PathVariable("id") int id){
for (student s : students) {
if(s.getId() == id)
return students.remove(s);
}
return false;
}
}
-
输入localhost:8080/swagger-ui.html，打开swagger-ui界面
-
查看并测试API接口
进入post方法，parameters展示了后台接收的参数，后面的描述对应ApiImplicitParam中的value，点击Try it out
输入参数值后点击Execute运行
然后就可以在下方查看到后台返回结果了
- 验证是否真的上传成功
同样的操作使用获取所有学生信息的GET接口，可以发现刚刚插入的id为3，名字为ys的学生已经插入了
四、swagger在项目中的好处
- 前后端可以只通过swagger-ui.html交互，前端完全不需要后台代码，只用看API文档就可以调用相应接口。
- 有时需要往数据库中插入测试数据，但是不建议直接操作数据库加入数据，直接在数据库中加入的时候有时会影响后台插入数据，而后台又需要写代码插入不同数据，非常麻烦，使用swagger-ui调用post方法，可视化地去添加数据，方便快捷。
- 及时更新。后台代码更新后，无需后台人员区更改API接口文档，swagger直接同步了。
五、美化界面
有时候swagger界面比较难以操作，特别是需要不断切换接口时，点击起来比较麻烦，而且很多人不喜欢swagger界面的样式，这里提供一个用bootstrap渲染的swagger界面
- pom.xml加入依赖
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.6</version>
</dependency>
- 打开localhost:8080/doc.html，界面变成下面这样
