在之前的文章中，我们已经讲了如何利用SpringBoot来集成Swagger详情可戳：SpringBoot集成Swagger构建强大的API文档。但其实Swagger2中主流的2自2018年发布后就已经好久没更新了，而在时隔两年之后的2020年，Swagger3终于发布了。
相比于之前的SwaggerSwagger3无疑新添了更多的特点，而相对集中地，主要集中在如下几点。
支持OpenApi0.3兼容Swagger2的注释，而且进一步丰富了openAPI0的规范支持Webflux
既然Swagger3有了这么多的改变，那用法是不是还和Swagger2一样呢？答案是：不一样。
不过虽然两者的使用方式不一样，但是总体流程还是差不多了，只不过有些步骤有所小变动而已，只要你掌握了Swagger2的使用方法，那使用Swagger3起来就是需要注意小改动就行了。那接下来，我们就来看看，如何利用SpringBoot来集成Swagger对我们的Swagger2进行一次升级！
创建SpringBoot项目
同样的，开始之前，我们需要创建一个简单的SpringBoot项目，这里不展开讲了，如果你对此还有所疑惑，可以先去熟悉下，这里建议参考我之前写过的一篇文章：创建SpringBoot项目的3种方式。
项目创建成功之后，总体结构如下：
这里的config、controller、entity模块是我后续加入的，所以不用理会，也就是说你创建好之后的项目是不包含这三个部分的，关于他们的用途，文章后续内容我会讲到。
引入依赖
创建项目后，在poxml文件中引入Swagger3的相关依赖。回忆一下，我们集成Swagger2时，引入的依赖如下：
io.springfox
springfox-swagger2
2.9.2
io.springfox
springfox-swagger-ui
2.9.2
而在Swagger3中，我们不需要再引入两个不同的依赖了，我们只需要引入一个依赖就足够，具体引入的依赖如下：
io.springfox
springfox-boot-starter
3.0.0
而这部分，Swagger2和Swagger3就有所不同了，Swagger2需要添加两项不同依赖，而Swagger3只用添加一项依赖就可以了。
构建Swagger配置类
为了统一管理Swagger，这里还是推荐给Swagger3添加一个配置类。当然这里也可以根据自己的需求，可要可不要，但总体来说还是建议配置。
在之前集成Swagger2的文章中，忘记了给大家说一点。平常在工作中，Swagger的使用仅限于在开发环境，而在生产环境中，我们是要将其移除的。这里为了灵活管理，推荐大家在项目配置文件applicatioyml中添加关于Swagger开关的配置，比如这里我添加的配置如下，true则代表开启Swagger，false则表示关闭Swagger。
配置完成之后，我们就需要在Swagger配置类中获取Swagger开关的值了，关于具体用法就可以看下边配置代码。
package com.cunyu.springbootswagger3demo.config;
import org.springframework.beans.factory.annotation.Value;
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.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import java.util.ArrayList;
/**
* Created with IntelliJ IDEA.
*
* @author : 村雨遥
* @version : 1.0
* @project : springboot-swagger3-demo
* @package : com.cunyu.springbootswagger3demo.config
* @className : SwaggerConfig
* @createTime : 2022/1/6 14:19
* @email : 747731461@qq.com
* @微信 : cunyu1024
* @公众号 : 村雨遥
* @网站 : https://cunyu1943.github.io
* @description :
*/
@Configuration
@EnableOpenApi
public class SwaggerConfig {
/**
* 用于读取配置文件 application.properties 中 swagger 属性是否开启
*/
@Value('${swagger.enabled}')
Boolean swaggerEnabled;
@Bean
public Docket docket() {
return new Docket(DocumentationType.OAS_30)
.apiInfo(apiInfo())
// 是否开启swagger
.enable(swaggerEnabled)
.select()
// 过滤条件，扫描指定路径下的文件
.apis(RequestHandlerSelectors.basePackage('com.cunyu.springbootswagger3demo.controller'))
// 指定路径处理，PathSelectors.any()代表不过滤任何路径
//.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
/*作者信息*/
Contact contact = new Contact('村雨遥', 'https://cunyu1943.github.io', '747731461@qq.com');
return new ApiInfo(
'Spring Boot 集成 Swagger3 测试',
'Spring Boot 集成 Swagger3 测试接口文档',
'v1.0',
'https://cunyu1943.github.io',
contact,
'Apache 2.0',
'http://www.apache.org/licenses/LICENSE-2.0',
new ArrayList()
);
}
}
这里的配置和Swagger2大同小异，这里最大的区别在于加入了从配置文件中获取Swagger开关的属性。这里也可以选择添加到Swagger2的配置类中，同样通过配置文件来控制是否开启Swagger此外，还有就是DocumentationType属性的不同了，Swagger2中我们使用的是SWAGGER_而在Swagger3中，我们使用的则是OAS_30。其实点进去DocumentationType的源码我们就可以发现，Swagger已经是给我们定义好的，你用的是哪一个版本的Swagger，那我们使用的属性值应该选择对应版本。三个版本的属性值对应如下：
public static final DocumentationType SWAGGER_12 = new DocumentationType('swagger', '1.2');
public static final DocumentationType SWAGGER_2 = new DocumentationType('swagger', '2.0');
public static final DocumentationType OAS_30 = new DocumentationType('openApi', '3.0');
编写实体类
完成上面的步骤之后，我们的Swagger就配置好了，接下来我们就添加一个接口来看看Swagger3和Swagger2的不同。
新建实体类
这里我以一个用户类为实例，带有name、age两个属性，也就是本文一开始项目结构截中entity包下的内容。
package com.cunyu.springbootswagger3demo.entity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
/**
* Created with IntelliJ IDEA.
*
* @author : 村雨遥
* @version : 1.0
* @project : springboot-swagger3-demo
* @package : com.cunyu.springbootswagger3demo.entity
* @className : User
* @createTime : 2022/1/6 11:17
* @email : 747731461@qq.com
* @微信 : cunyu1024
* @公众号 : 村雨遥
* @网站 : https://cunyu1943.github.io
* @description :
*/
@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel('用户实体类')
public class User {
@ApiModelProperty(value = '姓名', required = true, example = '村雨遥')
private String name;
@ApiModelProperty(value = '年龄', required = true, example = '20')
private Integer age;
}
新建接口
这里写了两个接口，一个是直接传参，另一种是通过利用创建的User实体类来传输，也就是项目结构中controller包中的内容。
package com.cunyu.springbootswagger3demo.controller;
import com.cunyu.springbootswagger3demo.entity.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
/**
* Created with IntelliJ IDEA.
*
* @author : 村雨遥
* @version : 1.0
* @project : springboot-swagger3-demo
* @package : com.cunyu.springbootswagger3demo.controller
* @className : UserController
* @createTime : 2022/1/6 11:02
* @email : 747731461@qq.com
* @微信 : cunyu1024
* @公众号 : 村雨遥
* @网站 : https://cunyu1943.github.io
* @description :
*/
@Api(tags = '测试')
@RestController
@RequestMapping('/user')
public class UserController {
@ApiOperation('测试接口1')
@PostMapping('/show1')
public String show1(@ApiParam(value = '姓名', required = true, example = '村雨遥') @RequestBody String name) {
return 'hello,' + name + ',welcome to springboot swagger3！';
}
@ApiOperation('测试接口2')
@PostMapping('/show2')
public String show2(@ApiParam(value = '用户对象', required = true) @RequestBody User user) {
return 'hello,' + user.getName() + ',welcome to springboot swagger3！';
}
}
查看并测试接口
启动我们的项目，然后在浏览器中访问如下地址，就可以访问项目的接口文档了。
访问上面的地址后，如果出现下面的界面，则说明集成Swagger3就成功了。
这里也要注意一点，Swagger2中的接口访问地址是：
这里Swagger2和Swagger3是不同的，这里大家一定要注意，否则可能你继续拿着Swagger2接口访问地址来放到Swagger3项目中不适用。
点开具体接口，我们以直接传参的接口来对比Swagger3和Swagger2的区别。第一张是在Swagger3中，第二张是在Swagger2中。这里可以发现，我们都是传的一个name属性，Swagger2中会把我们接口中参数部分Parameters直接标识出来，而Swagger3中则不会，这里需要注意。
Swagger2中接口代码
@ApiOperation(value = '有参接口')
@PostMapping('demo')
public String demo(@ApiParam(value = '姓名', required = true, example = '村雨遥') @RequestBody String name) {
return 'hello,' + name;
}
Swagger3中接口代码
@ApiOperation('测试接口1')
@PostMapping('/show1')
public String show1(@ApiParam(value = '姓名', required = true, example = '村雨遥') @RequestBody String name) {
return 'hello,' + name + ',welcome to springboot swagger3！';
}
此外，我们来看Swagger3中的另一个接口，这里我们传递的是一个用户对象，接口中它将我们设置的默认值给传了过来。下中第一张为Swagger3中的截，第二张为Swagger2中的截。同样的，Swagger2中的参数会在Parameters模块标识出来，而Swagger3则不会标识。
还有一点值得注意的是，Swagger中如果传递的部分是对象，那么Swagger2会在Models部分进行标识，而Swagger3中则是变成了Schemas部分，这也算是一个小变动吧。
我们同样来进行测试，测试方法同Swagger点击接口右上方的Tryitout，然后编辑参数的值，编辑完成后点击下方的Execute即可查看接口调用结果。
经过上面的步骤，我们就完成了SpringBoot集成Swagger3的实例测试了，而经过对比，也总结出了Swagger2和Swagger3的区别主要体现在如下几个方面：
所需依赖不同，Swagger2需要添加两个依赖，而Swagger3则只需要添加一个依赖；启用Swagger的注解不同，不知道大家有没有发现，无论是Swagger2还是Swagger3中的配置类，其实都是有一个注解用来启用Swagger的，不同之处在于Swagger2中用的是@EnableSwagger而Swagger3中则用的是@EnableOpenApi；文档摘要信息文件类型不同，可以发现在Swagger的配置类中，Swagger2用的是SWAGGER_而Swagger3中则用的是OAS_3；SwaggerUI访问地址不同，在Swagger2中，如果我们要访问文档地址，需要访问http://localhost:8080/swagger-uhtml，而在Swagger3中，则是访问http://localhost:8080/swagger-ui/index.html；
总结
以上就是本文的所有内容了，主要介绍了如何使用SpringBoot集成Swagger并在此过程中对比了Swagger2和Swagger3的一些区别。总体来讲，Swagger2向Swagger3的升级还是比较平滑的。如果你已经掌握熟练使用Swagger那么向Swagger3过度也很简单，只需要注意上一部分中的一些主要区别就可以了。其他的用于描述接口的注解，还是可以按照Swagger2的方式使用，毕竟Swagger3向下兼容了Swagger
代码示例
关于本文示例的代码，我已经上传至GitCode，需要的小伙伴可以自取：
如果您觉得本文不错，欢迎Star支持，您的关注就是我坚持不断更新的动力！
文章为作者独立观点，不代表股票交易接口观点
相关文章
股民评论