【原】Swagger入门教程（五）

Swagger-UI 生成界面使用详解

1. 前言

本节会为大家介绍 Swagger 生成界面，即 Swagger-UI 界面的基础使用方法，包括界面基本元素讲解、界面接口内容讲解以及如何使用 Swagger-UI 界面进行必要的接口调试。

关于如何集成 Swagger 以及如何查看 Swagger-UI 界面请参考上一章节中的 'SpringBoot 集成 Swgger-UI’ 小节内容，本节不再赘述。

重点讲解内容：

• Swagger-UI 界面所有基本元素，界面接口基本内容；

• 基于 Swagger-UI 界面进行必要的接口调试。

掌握 Swagger-UI 界面的使用方法是使用 Swagger 进行接口调试的基本组成方式，所以请大家重点掌握该部分内容。

2.  Swagger-UI 界面基本元素介绍

在本部分我将以图文并茂的方式介绍在 Swagger-UI 界面上的基本元素，这些基本元素在界面的不同区域，是界面的基本组成元素。

我将按照 Swagger-UI 界面基本元素所处的不同区域依次介绍每个基本元素的含义和作用，下面我们都来看看有哪些基本元素以及他们所发挥的作用吧！

在配置好 Swagger 之后，我们在浏览器地址栏中输入项目中 Swagger-UI 界面的路径即可看到如上图所示的界面，这就是 Swagger-UI 的核心界面，也是我们使用最多的界面，项目中所有的接口都会在该界面上显示。

我们从上到下，依次进行介绍：

2.1 第一部分 顶部区域

在顶部栏区域的最左侧是 Swagger 的 Logo 图标，我们不需要关心。

在顶部栏区域的最右侧是一个 Explore 按钮，该按钮的作用就是刷新 Swagger-UI 界面，在我们点击时就会刷新，没有其他用途。

在 Explore 按钮的左侧，是 Swagger-UI 加载 html 界面模板的区域，这是一个下拉框，可以选择我们自定义的界面显示。

2.2 第二部分 中部区域

在中部区域可以看到只有最左侧有内容，在右侧是没有任何内容显示的。

在中部区域可以看到一行加粗加黑的字体：“immooc-Swagger-UI-Studying”，这里是用来描述 Swagger-UI 界面所显示的主要内容，一般使用我们的项目名称来描述。

在加粗加黑字体的下方是一行黑色的小字体：“Created by Steafan”，这里是用来描述 Swagger-UI 界面的作者信息，一般是接口维护人员或者接口开发人员。

2.3 第三部分 底部区域

在底部最开始的地方，我们可以看到 “user:User Controller” 等字样，这是我们使用 @ApiOperation 注解的 tags 属性来为接口描述的分组名称，当我们点击 user 之后，字体会加粗显示，同时会列出所有属于该 user 分组的接口列表，如下图所示：

而 User Controller 则是我们这些接口所属的 Java 类的名称，这里的名称通过 @Api 注解描述。

在最底部区域可以看到 “BASE URL” 字样，这里的 base url 指的是 Swagger-UI 界面的访问路径，即：http://host:port/imooc/imooc-user-service/swagger-ui.html （这里的路径是自己配置的），右侧的 API VERSION 代表当前接口的版本。

在上述部分，我们介绍了 Swagger-UI 界面的所有基本元素，接下来我们来看看我们开发的接口在 Swagger-UI 界面中都有哪些内容。

3. 接口基本内容介绍

在接口列表中，我们点开之前一直使用的用户登录接口 (login.do)，会显示出接口的所有内容信息，由于接口内容太长，所以我们分块进行讲解：

3.1 第一部分 Response Class

我们可以看到在图片的最上方是一个接口标题，其中，POST 代表接口的请求类型，/user/login.do 代表接口的地址以及接口名称，最右侧的用户登录就是我们使用 @ApiOperation 注解的 value 属性所描述的接口的作用。

Response Class 表示接口的响应信息，即我们请求接口时返回的响应内容，Status 200 表示该接口是可以正常使用的（接口状态的编码及意义请自行查阅，本节不做介绍）。Example Value 是 Swagger 自动生成的接口返回信息的模板，这也是接口真正的返回信息。

Response Content Type 是一个下拉框，表示接口所返回信息的类型，这里是 Swagger 的默认设置，表示返回什么类型的信息都可以。

3.2 第二部分 Parameters

Parameter 列表示接口的请求字段名称，就是接口的请求值，这里描述的是一个 user 对象。

Value 列表示请求接口的真实字段值，就是我要使用这个接口都需要传递哪些参数。该列还有一个关键内容：Parameter content type ，这是一个下拉框，表示我们传递参数的请求头信息，这里的 application/json 表示我们以 json 的形式进行传递（json 表示什么意思请自行查阅，本节不做介绍）。

Description 列表示对接口请求值的描述信息，就是我们在向这个接口传递参数的时候的一些注意事项，这里没有描述，所以 Swagger 默认使用了字段名称来描述。

Parameter Type 列表示接口的请求字段的类型，就是我需要向这个接口传递什么类型的参数，这里是 body ，表示我们传递的请求字段的类型是一个对象，这是我们自己设置的。

Data Type 列表示请求该接口的真实字段值，就是我要向接口传递的具体参数值，由 Swagger 默认生成，和 Value 列相对应，我们可以直接复制该列的 Example Value 的内容粘贴到 Value 列中来进行接口调试，这样就不用我们在 Value 列手动去输入字段值了。

3.3 第三部分 Response Messages

HTTP Status Code 列表示接口请求返回的状态编码，不同的编码会对应不同的意义，和 Reason 列相对应：201 - 表示已建立接口连接，401 - 表示接口无权限访问，403 - 表示接口访问被禁止，404 - 表示在当前路径下找不到该接口，接口无法返回信息。

• Response Model 列表示我们使用 @Response 注解定义的内容，表示接口的响应策略，这里只需要知道表示什么意思就行，一般很少使用。

Headers 列表示接口返回信息的响应头类型，这里我们简单了解就行。

在左下角有一个 Try it out! 按钮，该按钮就是用来调试接口的。具体如何调试接口本节不做介绍，我会使用专门一节的内容来介绍如何使用 Swagger-UI 进行接口调试。

4. 基于 Swagger-UI 界面的接口调试

调试的目的：

我们都知道，在实际项目开发中，当我们的接口开发完毕之后需要进行一些必要的自行测试，目的就是来看看我们自己所开发的接口有没有低级错误和基本错误，在进行自测之前，我们先来了解一下什么是低级错误，什么是基本错误。

低级错误一般是指接口的请求方法没有按照接口文档或者需求来规定，对外暴露的接口地址并不能被请求到。

基本错误一般是指接口中的参数类型在开发时没有根据接口文档或者需求来定义，接口的返回数据中由于程序引起的返回空值或没有返回任何内容。

调试的方法：

在上述内容中，我们已经对 Swagger-UI 界面进行了基本详细的介绍。我们以一个用户登录接口为例，来看看如何在 Swagger-UI 界面上进行接口自测试。

4.1 第一步：找到需要测试的接口

这一步很简单，只需要我们在浏览器中输入 Swagger 生成的 Swagger-UI 界面地址即可，在浏览器加载完毕后，我们可以在界面上看到我们项目中的所有接口，在这些接口列表中需要测试哪个接口，我们只需要点击接口名称即可，如下图所示：

4.2 第二步：填充参数并执行测试

针对接口的内容区域，我们已经在上述内容中进行了详细介绍，这里直接步入正题。

点击接口内容区域的 try it out 按钮，将锁定的 Example Value 区域解锁，解锁之后的界面如上图所示。

• 我们需要在标签 1 的位置填充接口的请求参数。

• 我们需要在标签 2 的位置选择请求接口的请求头类型，一般都为 application/json 类型，这也是 Swagger 默认自带的类型，一般不需要再次选择。

这里我们就以截图中的测试数据为例：

{  "adminPassword": "string",  "adminUser": "string",  "createTime": "string",  "id": 0,  "updateTime": "string"}

在两个位置的内容都填充好之后，我们点击 Execute 按钮来执行我们的接口请求。等待片刻之后我们就会在接口内容区域的最下方看到我们请求所对应的接口响应结果：

• 红色箭头指向的地方表明我们已经点击了 Execute 按钮，即请求已经发送成功了。

• 标签 1 区域表明接口的请求路径 Url ，我们可以在这个地方检查是否和接口文档或需求所要求的接口地址一致。

• 标签 2 区域表明接口的响应返回结果，分为 Code 和 Details 区域，其中，Code 表明返回状态码，这里是 200 表明接口请求成功，Details 表示请求接口成功时所返回的响应结果。

接口自测试总结

在执行完上述两个步骤之后，我们就完成了一个接口的自测试，通过在 Swagger-UI 界面上进行接口自测试我们可以很清楚地看到接口的路径是否正确、接口的请求参数是否正确、接口的返回结果是否正确，通过这种方式我们很好地降低了一个接口的低级错误和基本错误，这在实际项目开发中是非常重要的。

5. 小结

本小节对 Swagger 三剑客之一 Swagger-UI 生成界面进行了详细的讲解，采用图文并茂、要点击破的方式对生成界面的每一个基本元素和接口内容都做了详细的讲解和必要的补充，针对需要重点掌握的内容使用了加粗显示，旨在帮助大家在理解 Swagger-UI 生成界面基本概念的同时也要懂得如何使用 Swagger-UI 生成界面来查看接口基本内容、接口要点信息等。

在介绍完 Swagger-UI 生成界面的基本元素以及接口基本内容区域之后，我们还结合一个用户登录接口就如何基于 Swagger-UI 生成界面进行接口调试做了详细的介绍，通过分步实现的顺序对每一步骤中需要注意的地方单独做了讲解。

希望各位同学在学习本小节内容时可以结合自己的项目或者自己创建的 Demo 案例来学习，这是掌握本节内容最好最快的方式。

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 配置类进行一些必要的修改，修改好的配置类代码如下：

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

Swagger Codegen 简介

1. 前言

大家好，今天为大家介绍Swagger Codegen。Swagger Codegen 相信各位在中大型项目中都使用过，他的功能点和一些自带的特性可以支持绝大数项目的构建，话不多说，咱们直入正题。

2. 什么是 Swagger Codegen ？

什么是 Swagger Codegen 呢？在 Swagger 官网中是这么介绍的：

Swagger Codegen 可以通过为任何 API 生成服务端代码和客户端代码的方式来简化 OpenAPI 的构建过程，因此，项目开发团队可以更好地关注 API 的实现和应用。     —官网

这里提到的 OpenAPI 其实就是我们所谓的 RESTFUL API 规范，关于 RESTFUL API 规范我们已经在 Swagger 简介这一小节中做了详细的介绍，有不清楚的同学可以到该小节了解，这里不再赘述。

通过上面的介绍，说白了，Swagger Codegen 就是一款可以为我们构建服务端代码和客户端代码的工具，也可以把他理解为是一种代码生成框架，而且 Swagger Codegen 用的最多的地方也就是生成服务端和客户端代码。

3. 为什么要使用 Swagger Codegen ？

那么我们为什么要使用 Swagger Codegen 呢？

3.1 完善的代码生成器

对于小型项目而言，可能不会用到 Swagger Codegen ，而对于中型及以上规模的项目而言则是很有必要使用的。

我们可以想象这样一种场景：当我们的项目需求确定之后，需要步入到开发阶段时，我们首先做的就是对项目整体进行架构，即我们用什么语言，用什么框架来开发、完成这个项目，这就需要我们首先完成一些架构中的基础设施。

基础设施就是指我们所设计的项目目录、最基本的项目实体类、项目接口类、项目服务类，往往开发这些’基础设施’会耗费我们大量的时间。

所以，当我们在项目中使用了 Swagger Codegen 之后，我们只需要进行一定的配置，运行项目，即可生成我们项目中所需的这些基础设施，这在项目前期为我们节省了大量的时间，使得我们可以把时间用在集中处理项目业务上，提升我们的开发效率。

3.2 灵活的规则配置

在我们使用 Swagger Codegen 进行代码生成操作时，我们需要对生成的代码进行统一的规定，在规定完之后，Swagger Codegen 即可为我们生成符合我们要求的代码，而且每一个类都是符合规范的。

这就表明，我们可以在代码生成前灵活的对代码生成规则进行配置，这就使得在最终生成的代码中，我们不用再为代码规范所发愁，不用专门的去修改项目中不符合规范的代码了。

4. 学习基础

1. 学习 Swagger Codegen 这个工具需要大家真实开发过项目，并且使用的是 Java 7 或以上的 JDK 版本。

2. 如果你使用过前后端分离的模式构建项目，那么你在学习 Swagger Codegen 时相信会学的很快。

5. 小结

Swagger Codegen 其实就是一款可以为项目生成’基础设施’的代码生成器，包括服务端代码和客户端代码，其强大的生成器和灵活的规则配置可以大大提升在项目前期的编码效率以及项目整体代码的规则约束力，这也是 Swagger Codegen 的核心魅力。

Swagger Codengen 主流环境安装

1. 前言

本节会为大家介绍如何在当下主流操作系统中安装 Swagger Codegen 代码生成器。

重点讲解内容：

• 如何在 Windows 系统中安装 Swagger Codegen ；

• 如何在 OS X 系统 (Mac) 中安装 Swagger Codegen ；

• Swagger Codegen 安装是否成功的必要性测试。

2. 如何在 Windows 系统中安装 Swagger Codegen ?

针对 Windows 环境，Swagger Codegen 官方并没有直接提供很好的安装方法，所以这里我们采用另一种方式，这也是我总结出来的方法，屡试不爽。

2.1 第一步：获取 Swagger Codegen Jar 包

我们进入 Swagger Codegen 的开源界面，会得到官网所推荐的下载 jar 包的链接，链接比较长，这里我已经下好了，同学们可以直接从我的 Git 上进行下载：

https://github.com/SteafanMrZhou/MoocSwaggerWiki

2.2 第二步：在 Windows 环境 安装 Swagger Codegen

java -jar swagger-codegen-cli.jar help

运行以上命令之后，我们会得到很多关于 Swagger Codegen 的帮助信息，如下图所示：

由于我使用的是 Mac 系统，所以我在我的 Mac 上安装了 Win 的虚拟机来为大家演示。

3. 如何在 OS X 系统 (Mac) 中安装 Swagger Codegen

在 OS X 系统中安装 Swagger Codegen 和在 Windows 中安装 Swagger Codegen 大同小异，只是说我们所依赖的平台和安装的方式不同而已，接下来让我们来看看如何在 OS X 系统中安装 Swagger Codegen 吧。

3.1 第一步 确认 Mac 中是否已经安装 Homebrew

众所周知，如果你是使用 Mac 来工作的，那么你一定听说过 Hoembrew 了，Hoembrew 就类似于我们使用的 Maven ，但是不同于 Maven 的是，他即可以管理项目中的依赖包，也可以管理我们电脑中的依赖包，例如：Java 。

如何确认电脑中是否已经安装了 Homebrew 呢 ？ 我们可以在 Mac 的终端中使用以下命令确认：

brew

直接在终端中输入上述命令，然后按回车，如果会提示以下信息，说明 Homebrew 已经安装：

3.2 第二步 使用 Homebrew 安装 Swagger-Codegen

当我们的 Mac 中已经安装了 Hoembrew ，那么我们可以通过以下命令来安装 Swagger-Codegen ：

brew install swagger-codegen

如上图所示，如果你的 Homebrew 已经很长时间没使用了，那么他会自动更新 Homebrew 中已安装的依赖包，这需要等待一段时间。

在更新完 Homebrew 之后，我们可以等待 Swagger-Codegen 的安装完成，如下图所示：

可以看到，当我们输入 help 命令时并不会提示我们像 Windows 环境中的信息，这是因为在 Mac 环境中 Swagger-Codegen 所使用的命令格式和 Windows 中的不一样导致，这里就不再详细介绍了。

4. Swagger Codegen 安装是否成功的必要性测试及注意事项

4.1 Windows 环境

当我们运行 jar 包之后出现上述截图中所显示的帮助信息，说明我们下载的 jar 包是正确的，并且也说明 Swagger-Codegen 在我们的电脑中已经安装成功了，接下来就可以使用 Swagger-Codegen 为我们提供的命令来使用 Swagger Codegen 了。

4.2 OS X (Mac) 环境

和 Windows 环境一样，如果在 Homebrew 中安装 Swagger-Codegen 结束之后，给我们在终端打印出了 Swagger-Codegen 的帮助提示信息，那就说明我们在 Mac 中使用 Homebrew 安装 Swagger-Codegen 是成功的。

Tips :

1. 我们在安装 Swagger-Codegen 的时候，无论是 Windows 平台还是 OS X 平台，首先都需要将 Swagger-Codegen 的 jar 包下载下来，然后我们再针对平台分而治之，但是请记住，无论在哪个平台安装 Swagger-Codegen ，都要确保电脑上是 Java 7 以及更高的版本才行。

2. 一般在使用 Swagger-Codegen 的时候，绝大多数情况使用的都是 Swagger-Codegen 的最新稳定版本，所以各位在安装 Swagger-Codegen 时，务必要和本小节中使用的版本 (2.4.14) 保持一致，以免发生不必要的问题。

5. 小结

本小节针对当下主流操作系统，分别详细介绍了在 Windows 平台和 OS X (Mac) 平台安装 Swagger-Codegen 的步骤，以及在安装时候容易出现的问题，针对 Swagger-Codegen 的 Jar 包，考虑到自行下载可能下不动的情况，所以又额外提供了相关资源连接，同学们可以直接下载。