SpringBoot集成Swagger实战

Posted by hcy on April 3, 2020

为什么要使用Swagger

​ 作为后端,写完接口有时会忘记维护Api文档,时间长了接口文档和代码就相差甚远,导致文档难以维护且失去意义。使用Swagger,可以在写接口时顺便维护文档,从而接口变文档也变。并且文档页面还可以在线测试,且比手动写Markdown更美观。

​ 这篇文章将讲解如何在SpringBoot项目里面使用Swagger

1.创建Springboot项目

创建空的SpringBoot项目

​ 使用idea初始化SpringBoot项目,因为是web项目,别忘了勾选Spring Web依赖。

image-20200403132147933

添加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("张三", "李四", "赵六");
    }
}

测试接口

​ 在浏览器里顺利打开接口

image-20200403132815065

2.添加Swagger

添加依赖

1
2
3
4
5
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>

编写Swagger配置

Springfox需要编写一个DocketBean,在这个类里面做配置,下面是新建一个配置类,让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我们写的四个接口都在这里

image-20200403134554617

配置

配置文档标题和版本

​ 配置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());
    }

}

​ 界面变成了这样,文档名、版本、描述都变了。

image-20200403134110601

配置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

image-20200403135331799

更多配置

@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。

image-20200403140401482

​ 页面就会变成可编辑形式,点击Execute,就可以按照配置的参数发送请求了,并且下面会显示执行结果。

image-20200403140446596

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显示是这样的

image-20200403140957368

7.结束语

​ 本文就介绍到这里,基本能满足我们的需求,我们在修改接口时,顺便修改下注解就可以。同时前端在使用接口文档时,也可以在页面上直接测试接口。


转载请注明出处:https://www.huangchaoyu.com/2020/04/03/springboot集成swagger实战/