Swagger-UI 自定义界面

1. 前言

本节会为大家介绍如何自定义 Swagger-UI 生成界面。

一般来说，Swagger 为我们自动生成的界面就足以满足我们绝大多数的需求，然而避免不了需要根据业务需求定制 Swagger-UI 界面的情况，尽管这种情况很少。

本节作为 Swagger 三剑客之一 Swagger-UI 的组成部分，将会为大家介绍 Swagger-UI 主流的自定义实现方案，由于本套课程适合于初学者，所以很复杂的实现方式以及一些实现原理将不予介绍。

重点讲解内容：

• 主流自定义 Swagger-UI 界面实现方案对比；

• 基于 Swagger-ui-layer 实现自定义 Swagger-UI 界面。

2. 主流自定义 Swagger-UI 界面实现方案对比

对于自定义 Swagger-UI 界面的实现，目前有两种方法用得最多：

第一种：重定向 v2/api-docs 的访问路径到自己自定义的界面

由于 Swagger-UI 的解析原理是通过访问 v2/api-docs 路径下的 html 文件来解析 json 数据，使用这种方法我们首先需要自定义 html 文件，然后将 v2/api-docs 的访问路径指向我们自定义的 html 文件所在地址即可。

这种方法实现起来难度较大，并且需要开发人员掌握一定的前端 html 相关知识，还需要开发人员有一台属于自己的服务器来部署自定义的 html 文件，对绝大多数开发人员并不推荐使用该方法。

第二种：使用 Swagger-ui-layer 实现自定义 Swagger-UI 界面

出于强烈的 Swagger-UI 界面自定义需求，Swagger 的社区开始活跃了起来，前两年就可以在 Swagger 社区中看到 Swagger-ui-layer 这一名词。Swagger-ui-layer 是一款专门针对自定义 Swagger-UI 界面而开发的工具包，其支持 Java 平台等其他主流平台集成使用。

使用 Swagger-ui-layer ，我们只需要进行两步操作，即可完成自定义 Swagger-UI 界面的功能，这种方式集成方便，配置简单，是业界用得最多的一种方式，也是我推荐使用的一种方式，本文就是使用 Swagger-ui-layer 来介绍如何自定义 Swagger-UI 界面。

下面就让我们来看一下如何使用 Swagger-ui-layer 来实现自定义 Swagger-UI 界面吧！

3. 基于 Swagger-ui-layer 实现自定义 Swagger-UI 界面

使用 Swagger-ui-layer 来自定义 Swagger-UI 界面需要两步骤即可完成：

3.1 第一步 集成 Swagger-ui-layer 依赖到项目中

我们都知道，向项目中集成依赖的方式有很多种：我们可以直接把依赖包拷贝到项目中去，也可以通过主流包管理工具将依赖进行统一管理，从而将依赖集成到项目中去，本套课程在开篇时已经说明使用 Maven 包管理工具来构建项目，所以这里关于 Maven 的相关知识不再介绍，有不知道同学可以自己去查一下相关资料。

出于方便考虑，上述依赖截图对应下面依赖代码：

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.8.0</version>
</dependency>
<dependency>
  <groupId>com.github.caspar-chen</groupId>
  <artifactId>swagger-ui-layer</artifactId>
  <version>1.1.3</version>
</dependency>

代码解释：

上方的依赖为 Swagger 的依赖，下放的依赖为 Swagger-ui-layer 的依赖，同学们可以直接将上述两个依赖直接拷贝到自己项目的 pom 文件中去。

在将依赖拷贝到项目的 pom 文件中去后，等待依赖加载完毕即可。

3.2 第二步 对 Swagger-ui-layer 进行必要的配置

这里我们需要对上一章节中介绍的 Swagger 配置类进行一些必要的修改，修改好的配置类代码如下：

@Bean
public Docket ProductApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .genericModelSubstitutes(DeferredResult.class)
            .useDefaultResponseMessages(false)
            .forCodeGeneration(false)
            .pathMapping("/")
            .select()
            .build()
            .apiInfo(productApiInfo());
    }

private ApiInfo productApiInfo() {

ApiInfo apiInfo = new ApiInfo("慕课 Wiki Swagger 课程数据接口文档",
        "慕课 Swagger-Wiki 演示系统",
        "1.0.0",
        "API TERMS URL",
        "联系人邮箱",
        "license",
        "license url");
      return apiInfo;
    }

代码解释：

第 2 行，我们通过 DocumentationType.SWAGGER_2 属性声明项目中所使用的接口文档类型是 Swagger 2 版本的，这是必须的。

第 9 行，我们通过向 apiInfo 方法将我们自定义的 Swagger 界面描述信息填充到 Swagger-UI 中去。

第 12 行，在 productApiInfo 方法内部，我们对 Swagger 界面上所展示的信息进行一些必要的描述。

以上就是配置类的最关键的三个部分，当我们配置完这些属性之后，启动我们的项目即可看到界面效果。

显示效果：

Tips :

1. 注意 Swagger-ui-layer 开源工具的版本和 Swagger 版本的区别，虽然官网上说 Swagger-ui-layer 的版本并不会因为 Swagger 版本的变迁而受到影响，但是这里还是要说一句：如果是 Swagger 2.0 或以上版本，则请使用 Swagger-ui-layer 的最新版本 1.1.3。
2. 一般情况下，我们不需要针对 Swagger-UI 界面进行自定义配置，如有特殊要求，例如公司或企业定制时才会用到，然而，使用 Swagger-ui-layer 是最常用的方案。
3. 本节只是对 Swagger-ui-layer 进行一个相对简单的介绍，如果同学们感兴趣可以去 Swagger-ui-layer 的 github 上获取更多相关资料，出于对开源贡献者的尊敬，这里附上链接地址：https://github.com/caspar-chen/swagger-ui-layer 。

4. 小结

本小节针对如何自定义 Swagger-UI 界面做了详细的介绍，从当前可用的两个主流方案开始，通过对比当下主流方案的区别，选择了适合本课程的实现方案，同时针对该实现方案在具体实操环节中容易出现的问题做了必要的提醒，希望同学们在实操的时候可以一次成功。