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 进行简单必要的接口调试进行系统性地详细介绍，请各位同学关注。