Spring Boot 基础教程:使用 Swagger3 生成 API 接口文档

前言

在之前的文章中,我们已经讲了如何利用 Spring Boot 来集成 Swagger2,详情可戳:Spring Boot 集成 Swagger2,构建强大的 API 文档。但其实 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 项目,这里不展开讲了,如果你对此还有所疑惑,可以先去熟悉下,这里建议参考我之前写过的一篇文章:创建 Spring Boot 项目的 3 种方式

项目创建成功之后,总体结构如下:

Spring Boot 基础教程:使用 Swagger3 生成 API 接口文档

这里的 configcontrollerentity 模块是我后续加入的,所以不用理会,也就是说你创建好之后的项目是不包含这三个部分的,关于他们的用途,文章后续内容我会讲到。

引入依赖

创建项目后,在 pom.xml 文件中引入 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 的使用仅限于在开发环境,而在生产环境中,我们是要将其移除的。这里为了灵活管理,推荐大家在项目配置文件 application.yml 中添加关于 Swagger 开关的配置,比如这里我添加的配置如下,true 则代表开启 Swagger,false 则表示关闭 Swagger。

swagger:

 enabled: true

配置完成之后,我们就需要在 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 的配置类中,同样通过配置文件来控制是否开启 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. 新建实体类

这里我以一个用户类为实例,带有 nameage 两个属性,也就是本文一开始项目结构截图中 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;

}

  1. 新建接口

这里写了两个接口,一个是直接传参,另一种是通过利用创建的 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!";

   }

}

查看并测试接口

启动我们的项目,然后在浏览器中访问如下地址,就可以访问项目的接口文档了。

http://localhost:8080/swagger-ui/index.html

访问上面的地址后,如果出现下面的界面,则说明集成 Swagger3 就成功了。

这里也要注意一点,Swagger2 中的接口访问地址是:

http://localhost:8080/swagger-ui.html

这里 Swagger2 和 Swagger3 是不同的,这里大家一定要注意,否则可能你继续拿着 Swagger2 接口访问地址来放到 Swagger3 项目中不适用。

Spring Boot 基础教程:使用 Swagger3 生成 API 接口文档

点开具体接口,我们以直接传参的接口来对比 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!";

}

Spring Boot 基础教程:使用 Swagger3 生成 API 接口文档

Spring Boot 基础教程:使用 Swagger3 生成 API 接口文档

此外,我们来看 Swagger3 中的另一个接口,这里我们传递的是一个用户对象,接口中它将我们设置的默认值给传了过来。下图中第一张图为 Swagger3 中的截图,第二张图为 Swagger2 中的截图。同样的,Swagger2 中的参数会在 Parameters 模块标识出来,而 Swagger3 则不会标识。

还有一点值得注意的是,Swagger 中如果传递的部分是对象,那么 Swagger2 会在 Models 部分进行标识,而 Swagger3 中则是变成了 Schemas 部分,这也算是一个小变动吧。

Spring Boot 基础教程:使用 Swagger3 生成 API 接口文档

Spring Boot 基础教程:使用 Swagger3 生成 API 接口文档

最后,我们同样来进行测试,测试方法同 Swagger2,点击接口右上方的 Try it out,然后编辑参数的值,编辑完成后点击下方的 Execute 即可查看接口调用结果。

Spring Boot 基础教程:使用 Swagger3 生成 API 接口文档

Swagger2 VS Swagger3

经过上面的步骤,我们就完成了 Spring Boot 集成 Swagger3 的实例测试了,而经过对比,也总结出了 Swagger2 和 Swagger3 的区别主要体现在如下几个方面:

  1. 所需依赖不同,Swagger2 需要添加两个依赖,而 Swagger3 则只需要添加一个依赖;
  2. 启用 Swagger 的注解不同,不知道大家有没有发现,无论是 Swagger2 还是 Swagger3 中的配置类,其实都是有一个注解用来启用 Swagger 的,不同之处在于 Swagger2 中用的是 @EnableSwagger2,而 Swagger3 中则用的是 @EnableOpenApi
  3. 文档摘要信息(Docket)文件类型不同,可以发现在 Swagger 的配置类中,Swagger2 用的是 SWAGGER_2,而 Swagger3 中则用的是 OAS_3
  4. Swagger UI 访问地址不同,在 Swagger2 中,如果我们要访问文档地址,需要访问 http://localhost:8080/swagger-ui.html,而在 Swagger3 中,则是访问 http://localhost:8080/swagger-ui/index.html

总结

以上就是本文的所有内容了,主要介绍了如何使用 Spring Boot 集成 Swagger3,并在此过程中对比了 Swagger2 和 Swagger3 的一些区别。总体来讲,Swagger2 向 Swagger3 的升级还是比较平滑的。如果你已经掌握熟练使用 Swagger2,那么向 Swagger3 过度也很简单,只需要注意上一部分中的一些主要区别就可以了。其他的用于描述接口的注解,还是可以按照 Swagger2 的方式使用,毕竟 Swagger3 向下兼容了 Swagger2。

代码示例

最后,关于本文示例的代码,我已经上传至 Github,需要的小伙伴可以自取:

????传送门:https://github.com/cunyu1943/java-learning-demos

如果您觉得本文不错,欢迎 Star 支持,您的关注就是我坚持不断更新的动力!

上一篇:191014


下一篇:python的安装