为什么要使用Swagger
作为后端,写完接口有时会忘记维护Api
文档,时间长了接口文档和代码就相差甚远,导致文档难以维护且失去意义。使用Swagger
,可以在写接口时顺便维护文档,从而接口变文档也变。并且文档页面还可以在线测试,且比手动写Markdown
更美观。
这篇文章将讲解如何在SpringBoot
项目里面使用Swagger
。
1.创建Springboot
项目
创建空的SpringBoot
项目
使用idea
初始化SpringBoot
项目,因为是web项目,别忘了勾选Spring Web
依赖。
添加controller
创建一个如下增删改查的Controller
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
@RestController
@RequestMapping("test")
public class TestController {
@PostMapping("create")
public int create(String name, Integer age) {
return 1;
}
@PostMapping("delete")
public int delete(int id) {
return 1;
}
@PostMapping("update")
public int update(int id, String name, Integer age) {
return 1;
}
@GetMapping("get_all")
public List<String> get() {
return Arrays.asList("张三", "李四", "赵六");
}
}
测试接口
在浏览器里顺利打开接口
2.添加Swagger
添加依赖
1
2
3
4
5
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
编写Swagger
配置
Springfox
需要编写一个Docket
的Bean
,在这个类里面做配置,下面是新建一个配置类,让SpringBoot
扫描到这个Bean
并注入到容器。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
}
@EnableSwagger2
就是启动Swagger
功能。
访问验证
浏览器访问http://localhost:8080/v2/api-docs
,可以看到输出的一系列 Json
,可读性太差,但是Swagger
提供了一个可视化界面,方便我们阅读。
3.添加Swagger-Ui
添加依赖
1
2
3
4
5
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
访问
访问http://localhost:8080/swagger-ui.html
我们写的四个接口都在这里
配置
配置文档标题和版本
配置Swagger
需要提供一个ApiInfo
类描述文档标题,版本,用户名,邮箱等信息,像下面这样添加到Docket
里面。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build().apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
return new ApiInfo("测试开发文档", "开发文档描述", "0.01",
null, null,
"", "", Collections.emptyList());
}
}
界面变成了这样,文档名、版本、描述都变了。
配置Controller描述
类上添加注解@Api
,并填写tags
可以配置controller
描述
1
2
3
4
@RestController
@RequestMapping("test")
@Api(tags = "测试相关接口")
public class TestController {
配置接口名
给方法添加注解,可以配置接口名称,添加 @ApiOperation
注解在接口方法上。
1
2
3
4
5
@ApiOperation("获取所有数据")
@GetMapping("get_all")
public List<String> get() {
return Arrays.asList("张三", "李四", "赵六");
}
配置参数名
使用注解@ApiImplicitParams
可以配置多个参数,使用注解@ApiImplicitParam
可以配置一个参数。
1
2
3
4
5
6
7
8
9
10
@ApiOperation("根据id更新")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "用户id", required = true),
@ApiImplicitParam(name = "name", value = "用户名"),
@ApiImplicitParam(name = "age", value = "用户年龄")
})
@PostMapping("update")
public int update(int id, String name, Integer age) {
return 1;
}
required
表示是否必填,默认是false
。
验证
页面变成了这样,controller
变成了@Api
标记的名称,每个接口名变成了@ApiOperation
指定的名称,
参数描述变成了@ApiImplicitParam
指定的value
。
更多配置
@ApiParam
注解
除了使用@ApiImplicitParam
外还可以使用@ApiParam
标记参数。这样可以省去name
属性,但是可能会让方法参数列表看起来混乱。
1
2
3
4
5
@ApiOperation("根据id删除")
@PostMapping("delete")
public int delete(@ApiParam(value = "要删除的用户id", required = true) int id) {
return 1;
}
当然这两种方式可以混合使用,只要不重复标记到同一个参数上就行。
4.在线测试接口
找到一个接口,点击Try it out。
页面就会变成可编辑形式,点击Execute,就可以按照配置的参数发送请求了,并且下面会显示执行结果。
5.注意事项
文件上传写法
有是后端需要处理上传文件,则请使用@ApiParam
注解,不要用@ApiImplicitParam
,这样在页面上测试时就能直接鼠标选择要上传的文件了。
这两个注解作用于MultipartFile
类型上的区别,读者可以亲自尝试对比下。
1
2
3
4
5
6
@RequestMapping("upload")
@ApiOperation("上传文件")
public int uploadFile(@ApiParam("需要上传的文件") MultipartFile file) {
return 1;
}
6.配置资源路径
1
2
3
4
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/swagger-ui/**").addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/");
}
需要指定请求方式
像下面这两种指定请求Method方式都可以。
1
2
@GetMapping("upload")
@RequestMapping(value = "upload",method = RequestMethod.GET)
如果不指定请求方式,Swagger
将尝试使用所有请求方式去调用接口,文档页面看起来会很乱的。
下面upload
接口就没指定请求方式,Swagger
显示是这样的
7.结束语
本文就介绍到这里,基本能满足我们的需求,我们在修改接口时,顺便修改下注解就可以。同时前端在使用接口文档时,也可以在页面上直接测试接口。
转载请注明出处:https://www.huangchaoyu.com/2020/04/03/springboot集成swagger实战/