Swagger3初体验

最近做项目需要前后端分离，所以需要接口文档给前端方便联调。手写文档是不可能的，这时就需要使用Swagger了。网上的教程大部分版本都在2.x甚至是1.x，很少有3.0的教程，我个人就是喜欢用最新版，所以我就来分享一下我使用Swagger3的体验和坑吧。

# 配置

这里就分享springboot版本的方法了，现在的项目应该都用springboot创建了吧。

导入Maven依赖

1
2
3
4
5


<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

在启动类上加上@EnableOpenApi就行了。

当然，这样只是默认的，我们要用肯定要配置一下，我们去创建一个Config类，在里面建立一个函数返回Docket类，我们所有的配置就在这个Docket类里配置。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


@Configuration
@EnableOpenApi
public class SwaggerConfig {
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.OAS_30)	//3.0版本用OAS_30这个标准
                .apiInfo(getApiInfo())
                .select()
                //扫描指定包下的接口
                .apis(RequestHandlerSelectors.basePackage("top.lbqaq.controller"))
                .build();
    }

    /**
     * 配置swagger信息
     */
    private ApiInfo getApiInfo(){
        //这里是作者信息，分别为姓名、个人主页、邮箱
        Contact contact = new Contact("luoboQAQ","https://lbqaq.top","123@xx.com");
        return new ApiInfo(
                "项目名",
                "项目描述",
                "版本",
                "项目主页",
                contact,
                "Apache 2.0",
                "https://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

这样一个带有个人信息的配置页就做好了。

# 注解

首先是2.0版本的注解，当然新版本也同样通用。

Swagger注解	简单说明
@Api(tags = “xxx模块说明”)	作用在模块类上
@ApiOperation(“xxx接口说明”)	作用在接口方法上
@ApiModel(“xxxPOJO说明”)	作用在模型类上：如VO、BO
@ApiModelProperty(value = “xxx属性说明”,hidden = true)	作用在类方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam(“xxx参数说明”)	作用在参数、方法和字段上，类似@ApiModelProperty

既然用了3.0，也就可以使用3.0的新注释。

先放上官网链接：

Swagger是底层，实现是由SpringFox来完成的，所以有些在Swagger文档里的注解放到SpringFox里就无法实现，比如@RequestBody这个注解就无法实现。下面就列举我测试过可以成功的注解：

在方法上进行注释

1
2
3


@Operation(summary = "这会显示在主页上",
        description = "这显示在内页里",
        tags = {"test"})	//会将接口分类出去

在参数上注释

1

@Parameter(description = "这里是描述", required = true)

只测了这么多，之前为了测试@RequestBody花了太多时间，结果一无所获。因为2.0的注解还能用，这里就挖个坑，等之后有时间再来完善吧。