SpringBoot 集成 Swagger-UI 详解

1. 前言

本套课程主要针对 Swagger-UI 在 SpringBoot 开发框架中的使用,本节内容是学习本套课程的开端。

在本节中将为大家介绍如何使用 SpringBoot 来集成 Swagger-UI ,包括集成 Swagger-UI 的具体详细步骤,以及在集成过程中的一些注意事项。

重点讲解内容:

  • SpringBoot 主流开发框架与 Swagger-UI 工具的集成步骤。

  • 集成过程中的一些经验和注意事项、Swagger-UI 不同版本与 SpringBoot 框架兼容问题。

2. SpringBoot 集成 Swagger-UI 的准备工作

我们知道,使用 Maven 来创建的项目会有专门的一个 pom.xml 文件,这个文件是我们项目中所有用到的工具包的一个列表,在 java 中被称作 jar 包。在 Maven 中通过引入不同的 jar 包坐标配置来将相应的工具集成到我们的项目中。

所以当我们需要在项目中集成某种工具时,我们需要将该工具对应的坐标放到 Maven 的 pom.xml 文件中去。

通过访问 Maven 的中央仓库我们可以搜索到 Swagger-UI 对应 SpringBoot 框架适合的坐标数据,如下 Maven 坐标所示:

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.6.1</version>
</dependency>

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>2.6.1</version>
</dependency>

在上述 Maven 坐标中,第一个 springfox-swagger2 依赖,为 Swagger 2 的核心依赖,即我们如果想使用 Swagger 工具,则必须要在项目中引入该依赖,如果我们没有引入该依赖,那么我们是不能在项目中使用 Swagger 的。

而 springfox-swagger-ui 这一依赖,就是我们本文所介绍的 Swagger-UI 的依赖,如果我们不引入该依赖,我们是不会看到 Swagger 的 API 管理界面的。

在将上述两个 Swagger 的坐标数据放到我们项目的 pom.xml 文件中去之后,我们就完成了集成 Swagger-UI 的准备工作。

这样引入的 Swagger-UI 我们只能使用它的注解,而这时所产生的 Swagger-ui 界面我们是看不懂的,因为我们还没有对界面增加我们的规定,所以接下来让我们完成 Swagger-UI 的一些基本配置。

3. 在 SpringBoot 中配置 Swagger-UI

由于 SpringBoot 框架简化了传统 Spring MVC 框架中繁琐的 xml 文件配置,所以我们在对 Swagger-UI 进行配置时只需要使用两个注解和一个配置类即可完成,SpringBoot 为我们提供了两种配置方法,让我们来看一下吧。

Tips : 在接下来的两种配置方法中,主要介绍 Swagger-UI 的集成注解,而对于配置类我会单独进行详细讲解,请同学们注意。

3.1 第一种方式 Swagger-UI 集成注解与配置类分开配置

Swagger-UI 官方针对 SpringBoot 框架推出了很方便的开放 API ,我们在引入了 Swagger-UI 的 Maven 坐标之后,只需要在 SpringBoot 应用的启动类的上方加入开启 Swagger-UI 的注解即可在项目中来使用 Swagger-UI。

在上图中,我添加了 @EnableSwagger2 注解,这正是 Swagger-UI 官方在 SpringBoot 框架中提供的开启使用 Swagger-UI 的注解。

当我们在项目的启动类上方添加了 @EnableSwagger2 注解之后就表示我们可以在项目中来使用 Swagger-UI 了。

Tips : 如果我们只引入了 Swagger-UI 的依赖,没有配置 @EnableSwagger2 注解,那么在项目中我们也是无法使用 Swagger-UI 的,这一点需要同学们特别注意。

对于 Swagger-UI 的配置类来说,我们只需要新建一个配置类并将该配置类通过添加 @Configuration 注解来注入到我们的项目中即可。

以上是配置 Swagger-UI 的第一种方法,即通过 @EnableSwagger2 注解与 @Configuration 注解相分离的方式来配置,这种配置方式相对来说好理解一些。

Tips:

  1. 各位同学在集成 Swagger-UI 时,依赖的版本请务必和老师保持一致,避免由于版本原因而出现的未知问题。
  2. SpringBoot 框架版本请选择 SpringBoot 2.0.X.RELEASE 及以上版本或 SpringBoot 的里程碑版本。
  3. @Configuration 注解贯穿整个 SpringBoot 框架,有不懂的同学请自行了解。

3.2 第二种方式 Swagger-UI 集成注解与配置类集中配置

在第一种方式中我们将两个注解进行了分开配置,这种方法通俗易懂,而在本方式中,会将两个注解集中来配置。

我们新建一个类,名为 Swagger2Config ,这个类就是我们后续要讲的 Swagger-UI 配置类了,然后我们在该类的最上方添加上述两个注解:

在上图中,我们通过在启动类中添加 @Configuration 注解的方式将配置类以及 Swagger-UI 的所有注解来一起注入到我们项目中去,这与第一种方式的不同之处在于:

第一种方式, @EnableSwagger2 注解的声明没有通过 @Configuration 注解来处理,而是通过 SpringBoot 应用去自动装配;第二种方式则是将配置类和 Swagger-UI 的所有注解都通过 @Configuration 注解来处理,不通过 SpringBoot 应用去自动装配

而上述两种方式并不会影响项目的正常运行,所以我们采用任何一种方式都是可取的。

4. Swagger-UI 配置类详解

在本部分中,老师将带领大家针对 Swagger-UI 常用的基本配置属性以及其他额外属性进行详细讲解,下面我们来看一下 Swagger-UI 都需要在 SpringBoot 框架中配置哪些属性(所有属性都根据官方配置演变而来)。

创建 Swagger 应用配置:

代码解释:

createRestApi 方法的返回值是一个 Docket 类型,该类型就是返回 Swagger-Documentation 类型的数据,大家不用关心。

在方法内部,使用匿名内部类的方式实例化了一个 Docket 对象并返回,DocumentationType 即文档类型的选择我们需要根据集成的 Swagger 的版本来选择,这里选择 SWAGGER_2 表示使用的 Swagger 是2.X系列版本。

apiInfo() 和 select() 这两个方法是配置 Swagger 应用的必要方法,我们只需要这样理解就可以了:集成必要的 API 信息(apiInfo() 方法)来供我们查询(select() 方法)使用。

apis() 方法里面通过 RequestHandlerSelectors.basePackage() 属性来描述我们的目标包,就是我们项目中接口所在包的完整目录名称,这样 Swagger 就可以扫描到了,如果不配置此项,Swagger 是扫描不到我们项目中的接口的。

paths() 方法就是规定将我们项目中所有接口的请求路径都暴露给 Swagger 来生成 Swagger-UI 界面。

build() 方法就是将我们设置的上述参数都放到返回的 Docket 实例中。

创建 Swagger-UI 界面基本信息配置:

代码解释:

apiInfo 方法返回 Swagger-ApiInfo 类型,大家可以理解为返回 Swagger-UI 界面的基本信息就行了。在方法内部也是通过匿名内部类的方式返回一个 ApiInfo 实例。

title() 方法:就是来规定我们的 Swagger-UI 界面的大标题。

description() 方法:就是来规定对 Swagger-UI 界面的一些简单描述信息。

contact() 方法:就是来规定创建 Swagger-UI 的作者的名称,目前已被废弃。

version() 方法:就是来规定 Swagger-UI 界面上所有接口的版本。

build() 方法:就是将我们设置的上述参数都放到返回的 ApiInfo 实例中。

通过上述两个方法的配置,我们就完成了 Swagger-UI 的基本配置,启动项目之后,在浏览器地址栏中输入访问路径(一般为项目 ip 地址:端口/swagger-ui.html)就可以在浏览器中看到 Swagger-UI 的界面效果了

Tips:

  1. 访问路径中的 swagger-ui.html 为默认固定写法,一般不用修改。
  2. createRestApi() 方法为 public 方法,即这个方法需要对外暴露才行,而 apiInfo() 方法为 private 私有方法;该方法的用途是配置 Swagger-UI 界面基本信息,只能在项目中进行配置,不能将配置权限暴露出去。
  3. 在 apiInfo() 方法中我们不需要写太多的信息,因为一些必要的信息都是在接口中来描述的。

5. 小结

本小节从 Swagger-UI 集成准备工作开始,到不同的配置集成方式,再到最后对 Swagger 配置类的详细阐述,从零到一的对 SpringBoot 如何集成 Swagger-UI 进行了详细的讲解,旨在帮助大家能够准确的集成 Swagger-UI ,对于在集成中容易出现的问题,老师也做了相应的提醒和解决建议,希望各位同学都能成功在 SpringBoot 中集成 Swagger-UI。

针对 Swagger-UI 界面上的每一个组成元素在这里就不系统介绍了,后面会有专门的小节来对 Swagger-UI 界面的组成元素以及如何使用 Swagger-UI 进行简单必要的接口调试进行系统性地详细介绍,请各位同学关注。