SpringBoot使⽤Swagger3⽣成API接⼝⽂档
前⾔
在之前的⽂章中，我们已经讲了如何利⽤ Spring Boot 来集成 Swagger2，详情可戳：。但其实 Swagger2 中主流的 2.9.2 ⾃ 2018 年发布后就已经好久没更新了，⽽在时隔两年之后的 2020 年，Swagger3 终于发布了。
相⽐于之前的 Swagger2，Swagger3 ⽆疑新添了更多的特点，⽽相对集中地，主要集中在如下⼏点。
⽀持 OpenApi 3.0.3
兼容 Swagger2 的注释，⽽且进⼀步丰富了 open API 3.0 的规范
⽀持 Webflux
既然 Swagger3 有了这么多的改变，那⽤法是不是还和 Swagger2 ⼀样呢？答案是：不⼀样。
不过虽然两者的使⽤⽅式不⼀样，但是总体流程还是差不多了，只不过有些步骤有所⼩变动⽽已，只要你掌握了 Swagger2 的使⽤⽅法，那使⽤ Swagger3 起来就是需要注意⼩改动就⾏了。那接下来，我们就来看看，如何利⽤ Spring Boot 来集成 Swagger3，对我们的Swagger2 进⾏⼀次升级！
Spring Boot 集成 Swagger
创建 Spring Boot 项⽬
同样的，开始之前，我们需要创建⼀个简单的 Spring Boot 项⽬，这⾥不展开讲了，如果你对此还有所疑惑，可以先去熟悉下，这⾥建议参考我之前写过的⼀篇⽂章：。
项⽬创建成功之后，总体结构如下：
这⾥的 config、controller、entity 模块是我后续加⼊的，所以不⽤理会，也就是说你创建好之后的项⽬是不包含这三个部分的，关于他们的⽤途，⽂章后续内容我会讲到。
引⼊依赖
创建项⽬后，在 l ⽂件中引⼊ Swagger3 的相关依赖。回忆⼀下，我们集成 Swagger2 时，引⼊的依赖如下：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
⽽在 Swagger3 中，我们不需要再引⼊两个不同的依赖了，我们只需要引⼊⼀个依赖就⾜够，具体引⼊的依赖如下：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
⽽这部分，Swagger2 和 Swagger3 就有所不同了，Swagger2 需要添加两项不同依赖，⽽ Swagger3 只⽤添加⼀项依赖就可以了。
构建 Swagger 配置类
为了统⼀管理 Swagger，这⾥还是推荐给 Swagger3 添加⼀个配置类。当然这⾥也可以根据⾃⼰的需求，可要可不要，但总体来说还是建议配置。
另外，在之前集成 Swagger2 的⽂章中，忘记了给⼤家说⼀点。平常在⼯作中，Swagger 的使⽤仅限于在开发环境，⽽在⽣产环境中，我们是要将其移除的。这⾥为了灵活管理，推荐⼤家在项⽬配置⽂件 l 中添加关于 Swagger 开关的配置，⽐如这⾥我添加的配置如下，true 则代表开启 Swagger，false 则表⽰关闭 Swagger。
swagger:
enabled: true
配置完成之后，我们就需要在 Swagger 配置类中获取 Swagger 开关的值了，关于具体⽤法就可以看下边配置代码。
package com.fig;
import org.springframework.beans.factory.annotation.Value;
import t.annotation.Bean;
import t.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.fig
* @className : SwaggerConfig
* @createTime : 2022/1/6 14:19
* @email : 747731461@qq
* @ : cunyu1024
* @ :springboot结构
* @⽹站 : cunyu1943.github.io
* @description :
*/
@Configuration
@EnableOpenApi
public class SwaggerConfig {
/**
* ⽤于读取配置⽂件 application.properties 中 swagger 属性是否开启
*/
@Value("${abled}")
Boolean swaggerEnabled;
@Bean
public Docket docket() {
public Docket docket() {
return new Docket(DocumentationType.OAS_30)
.apiInfo(apiInfo())
// 是否开启swagger
.enable(swaggerEnabled)
.select()
// 过滤条件，扫描指定路径下的⽂件
.apis(RequestHandlerSelectors.basePackage("com.ller"))
/
/ 指定路径处理，PathSelectors.any()代表不过滤任何路径
//.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
/*作者信息*/
Contact contact = new Contact("", "cunyu1943.github.io", "747731461@qq");
return new ApiInfo(
"Spring Boot 集成 Swagger3 测试",
"Spring Boot 集成 Swagger3 测试接⼝⽂档",
"v1.0",
"cunyu1943.github.io",
contact,
"Apache 2.0",
"/licenses/LICENSE-2.0",
new ArrayList()
);
}
}
这⾥的配置和 Swagger2 ⼤同⼩异，这⾥最⼤的区别在于加⼊了从配置⽂件中获取 Swagger 开关的属性。这⾥也可以选择添加到Swagger2 的配置类中，同样通过配置⽂件来控制是否开启 Swagger2。此外，还有就是 DocumentationType 属性的不同了，Swagger2中我们使⽤的是 SWAGGER_2，⽽在 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 的不同。
1. 新建实体类
这⾥我以⼀个⽤户类为实例，带有 name、age 两个属性，也就是本⽂⼀开始项⽬结构截图中 entity 包下的内容。
package com.ity;
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.ity
* @className : User
* @createTime : 2022/1/6 11:17
* @email : 747731461@qq
* @ : cunyu1024
* @ :
* @⽹站 : 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;
}
2. 新建接⼝
这⾥写了两个接⼝，⼀个是直接传参，另⼀种是通过利⽤创建的 User 实体类来传输，也就是项⽬结构中 controller 包中的内容。
版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。
发表评论