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 种方式。

项目创建成功之后，总体结构如下：

 

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

引入依赖

创建项目后，在 pom.xml 文件中引入 Swagger3 的相关依赖。回忆一下，我们集成 Swagger2 时，引入的依赖如下：

 

而这部分，Swagger2 和 Swagger3 就有所不同了，Swagger2 需要添加两项不同依赖，而 Swagger3 只用添加一项依赖就可以了。