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

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

 

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

引入依赖

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

 

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

 

posted @ 2022-01-18 08:07  Java团长  阅读(202)  评论(0编辑  收藏  举报