SpringBoot 集成 Swagger Codegen

1. 前言

本节会为大家介绍，如何基于 Spring Boot 集成 Swagger Codegen 到我们的项目中去，以及 Swagger Codegen 快速入门相关知识点，希望通过本节讲解，大家可以对 Swagger Codegen 有进一步的认识。

重点讲解内容：

• 如何将 Swagger Codegen 集成到 SpringBoot 中去；

• Swagger Codegen 快速入门与使用技巧。

2. 如何将 Swagger Codegen 集成到 SpringBoot 中去 ？

因为本套课程使用 Maven 包管理工具构建，所以在集成 Swagger Codegen 时我们需要如下两个步骤：

2.1 第一步：引入 Swagger Codegen 依赖

这里我将依赖放到了下方，同学们可以直接拷贝：

<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-codegen-maven-plugin</artifactId>
    <version>2.4.14</version>
</dependency>

等待编辑器下载完成后，没有任何依赖报错，就说明我们已经将 Swagger Codegen 的依赖引入到了 SpringBoot 中去。

2.2 第二步：配置 Swagger Codegen

我们知道，Swagger Codegen 主要的作用，就是生成服务端和客户端的完整代码文件，所以，在将 Swagger Codegen 集成到 Spring Boot 中后，我们首先需要做的就是，对生成服务端和客户端的代码进行规则配置，即我们都需要生成什么样的服务端和客户端代码。

配置服务端和客户端的代码生成规则叫繁琐，所以我们选择常用的几个属性来进行演示。

配置服务端代码生成规则

在 Swagger Codegen 中，配置服务端的代码生成规则，需要用到 yml 配置源文件，所以需要对 yml 配置源的语法有一定了解和掌握，有不清楚的同学请自行查阅相关资料。

swagger: '2.0'
info:
 title: IMooc Swagger-Wiki API
 description: Swagger-Wiki API
 version: 1.0.0
paths:
 /imooct/wiki/swagger:
   get:
     tags:
     - wiki
     operationId: getImoocLesson
     parameters:
     - name: range
       in: query
       type: string
       required: true
     - name: lessonName
       in: query
       type: string
       required: true
     - name: lessonType
       in: query
       type: string
     responses:
       '200':
         description: OK
         schema:
           $ref: '#/definitions/GetImoocLessonResponse'
       default:
         description: default
         schema:
           $ref: '#/definitions/ErrorResponse'

对于以上所使用的属性我们会在本节的后半部分进行详细介绍，这里大家可以先做简单的了解即可。

配置客户端代码生成规则

在 Swagger Codegen 中，客户端的代码规则是通过 json 文件来进行配置的，json 相信大家都很熟悉，这里就不再做相关介绍了。

{
 "apiPackage": "com.imooc.wiki.swagger.api",
 "artifactId": "cmp-imooc-steafan-service",
 "basePackage": "com.steafan.imooc.server",
 "configPackage": "com.steafan.imooc.server.config",
 "dateLibrary": "java8",
 "delegatePattern": true,
 "groupId": "com.steafan.imooc",
 "hideGenerationTimestamp": true,
 "java8": true,
 "language": "spring-boot",
 "modelPackage": "com.imooc.wiki.swagger.api"
}

代码解释：

basePackage ：用于声明 Swagger Codegen 在生成代码时所扫描的路径。

configPackage ：用于声明 Swagger Codegen 在生成代码时配置文件所在的目录。

dateLibrary ：用于声明 Swagger Codegen 在生成代码时所用的语言。

language ：用于声明 Swagger Codegen 在生成代码时所用的框架语言描述。

modelPackage ：用于声明 Swagger Codegen 在生成代码时项目中实体所在目录。

完成上述配置之后，我们就可以使用 Swagger Codegen 来生成服务端和客户端代码。

2.3 第三步：使用 Swagger Codegen 生成服务端和客户端代码

在将 Swagger Codegen 的依赖引入到 Spring Boot 中去后，我们就可以使用 Maven 自带的命令来将上述配置信息分别生成服务端和客户端代码，命令如下：

首先，将上述配置好的文件利用 Swagger Codegen 来生成服务端和客户端代码

  java -jar swagger-codegen-cli.jar generate -i swagger.yaml -c swaggerConfig.json -l spring -o server

代码解释：

第一行，使用 generate 命令来将配置在 swagger.yaml 文件中的服务端代码进行生成。

第一行，使用 -c 参数，表明使用 json 配置文件，并且该配置文件的名称为 swaggerConfig.json。

第二行，使用 -l 参数，表明客户端所使用的语言为 spring 。

第二行，使用 -o 参数来指定代码最终的存放位置，server 表示将生成的代码存放到名为 server 的文件夹下。

然后我们使用 cd 命令来进到我们生成代码后所存放的目录：

  cd server

最后我们将生成的代码打成 Jar 包:

  mvn package

这是 Maven 自带的打包命令，执行该命令之后，Maven 会默认读取项目中的 pom 文件中配置的打包规则，即 packaging 节点，如果该节点没有配置任何规则，则 Maven 会默认打成 Jar 包 (这里我们配置了 Jar)。

这样我们就可以在项目的 target 目录下，找到我们利用 Swagger Codegen 所生成的服务端和客户端代码的 Jar 包了，我们可以把该 Jar 包放到其他环境中使用，也可以供其他项目使用，这就是我们利用 Swagger Codegen 所生成的服务端和客户端代码的最终使用目的。

3. Swagger Codegen 快速入门与使用技巧

3.1 Swagger Codegen 快速入门

服务端

我们针对以上服务端配置的规则来介绍一下在 Swagger Codegen 服务端中经常使用的一些属性，同学在了解了这些属性之后就可以使用 Swagger Codegen 进行一些服务端代码的生成工作了。

swagger: '2.0'
  info:
   title: IMooc Swagger-Wiki API
   description: Swagger-Wiki API
   version: 1.0.0
  paths:
   /imooct/wiki/swagger:
     get:
       tags:
       - wiki
       operationId: getImoocLesson
       parameters:
       - name: range
         in: query
         type: string
         required: true
       responses:
         '200':
           description: OK
           schema:
             $ref: '#/definitions/GetImoocLessonResponse'

代码解释：

swagger : 指名生成的服务端代码所使用的 Swagger 管理版本，这里只能写 2.0 。

info : 表示 Swagger Codegen 所生成的服务端代码的一些基本描述信息，上述包括 title (头信息) 、 description (文档描述) 、 version (文档版本)。

paths : 表示具体一个接口的路径信息。

get : 表示该接口的 http 请求类型，get 即为 Get 请求，同理 post 即为 Post 请求，以此类推。

tags : 表示该接口所属的分组。

operationId : 表示该接口的名称。

parameters : 表示该接口中的参数信息，上述包括 name (参数名称) 、 in (参数用途) 、type (参数类型) 、 required (参数是否必传，true 表示参数必传，默认为 false )。

responses : 表示该接口的返回信息，这里的 200 表示接口返回状态码，description 代表当接口返回状态码为 200 时的状态码描述信息，schema 中的 ref 属性统一表示当该接口返回 200 时重定向的地址或接下来要发生的动作。

客户端

针对 Swagger Codegen 中客户端代码的配置，在前面已经做了一些较为详细的介绍了，这里我就常用的客户端配置代码给上述内容做一个补充，同学们需要结合着来了解。

{
  "apiPackage": "com.imooc.wiki.swagger.api",
  "artifactId": "cmp-imooc-steafan-service",
  "groupId": "com.steafan.imooc",
  "hideGenerationTimestamp": true,
}

代码解释：

apiPackage : 表示需要生成的客户端代码的包位置。

artifactId 、 groupId : 类似于 Maven 中的依赖坐标，这里表示所生成的客户端代码的坐标信息。

hideGenerationTimestamp : 表示在生成客户端代码之后会隐藏生成代码的时间，这个配置可有可无。

3.2 Swagger Codegen 使用技巧

服务端

我们在生成服务端代码时，不能盲目生成，如果已经有写好的接口文档，那么我们需要按照这个接口文档进行编写和配置，如果没有写好的接口文档，那么我们需要和产品经理进行都次反复的沟通之后才能开始编写和配置服务端信息，这样可以在很大程度上减少服务端配置文件修改的次数，同时也可以提高服务端生成代码的准确性，这点同学们需要注意。

客户端

在生成客户端代码时，我们需要和服务端的开发人员进行详细的沟通，确定代码生成范围以及所需要使用的代码，尽量避免生成多余的、无用的、低价值的代码，这样不仅仅浪费系统资源，同时也浪费了项目开发的时间，这点也需要同学们注意。

4. 小结

本小节从在 SpringBoot 中如何集成 Swagger Codegen 出发，详细介绍了如何在 SpringBoot 中将 Swagger Codegen 进行集成，以及在集成中容易出现的问题。在介绍完 Swagger Codegen 集成 SpringBoot 之后，针对零基础的同学，老师将在 Swagger Codegen 中使用的最多的属性单独拿出来做了介绍，旨在帮助同学们能够快速入门 Swagger Codegen。

各位同学在学习本小节内容时，希望各位可以跟着老师的节奏一行一行地把本小节中所将的代码都动手敲一下，这样可以加深自己对代码的理解程度，在实操时我们不能眼高手低，自己的实践结果才是最重要的。

Swagger Editor 简介

1. 前言

大家好，今天为大家介绍 Swagger Editor。Swagger Editor 和 Swagger Codegen 不同，Swagger Editor 适用于一切规模的项目，话不多说，咱们直入正题。

2. 什么是 Swagger Editor ？

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

Swagger Editor 是一个开源编辑器，我们可以在这个开源编辑器上设计、描述和记录我们的 API 信息，通过 Swagger Editor 这个开源编辑器进行配置而生成的 API 是符合 RESTFUL API 规范的，并且 Swagger Editor 这款开源编辑器支持 Swagger 2.0 版本和 RESTFUL API 3.0 版本。    —官网

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

通过上面的介绍，说白了，Swagger Editor 就是一款提供了可以直接设计、描述和记录项目中所有的接口为 RESTFUL API 文档的开源编辑器，可以帮助我们提升项目开发效率。

3. 为什么要使用 Swagger Editor ？

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

3.1 完善的 RESTFUL API 生成机制

对于任何规模大小的项目而言，无论是小项目还是大项目，都会涉及到项目接口的开发，而对于项目接口的管理，最常见的就是根据项目接口内容撰写项目接口文档，但是这种方式有一种显而易见的弊端。

当项目中接口开发的需求发生变化时，根据项目管理规范，我们需要首先修改之前撰写好的相应的接口文档，由于种种原因，导致我们的修改时机很慢而不能及时支撑该接口的修改交付工作，这就会产生冲突，就会不得已先进行接口的修改，后续再来修改接口文档了。

针对上述类似问题，如果我们使用 Swagger Editor 来对接口进行维护，就会大大降低这种问题出现的概率。

Swagger Editor 提供了强大的配置文件类型，例如我们熟知的 yml 配置源文件和少数的 json 配置源文件，针对这两种配置文件，Swagger Editor 内置了丰富的 RESTFUL API 属性，开发人员可以直接使用这些属性来描述项目中的接口信息，不需要专门再将接口修改为符合 RESTFUL API 规范而发愁了。

3.2 美观的界面显示效果

在第一章中，当我们在项目中集成了 Swagger 框架之后，运行项目之后会为我们生成 Swagger-ui 界面，我们都知道这个界面还是相对美观一些的，我们也可以直接在这个界面上浏览接口和其他信息。

Swagger Editor 在配置好之后的生成界面几乎是和 Swagger-ui 界面是一模一样的，而且 Swagger Editor 的生成界面允许我们边修改配置信息边查看修改结果，可以实时看到我们的修改结果。

这就表明，如果我们项目中的接口需求发生了变动，我们可以直接在 Swagger Editor 中修改相应的配置信息，并且可以实时看到修改结果，这对开发人员来说是一个’福音’。

4. 学习基础

学习 Swagger Editor 这个工具和 Swagger Codegen 一样，需要大家真实开发过项目并且对项目进行过简单的配置，并且使用的是 Java 7 或以上的 JDK 版本。

如果你是一名后端开发人员，那么相信你在学习 Swagger Editor 时会信手拈来。

5. 小结

Swagger Editor 其实就是一款可以为项目中的接口生成 RESTFUL API 规范界面的开源工具，其完善的 RESTFUL API 生成机制和美观的界面显示效果可以在提升项目接口的维护效率的同时增强接口文档的交互性，这也是 Swagger Editor 的核心魅力。

Swagger Editor 主流环境安装

1. 前言

本节会为大家介绍如何在当下主流操作系统中安装 Swagger Editor 开源 API 配置工具。

重点讲解内容：

• 如何基于 Node 环境安装 Swagger Editor ；

• 如何基于 Docker 环境安装 Swagger Editor ；

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

2. 如何基于 Node 环境安装 Swagger Editor

基于 Node 环境来安装 Swagger Editor ，是 Swagger Editor 官方推荐使用的第一种方式，通过 Node 来安装 Swagger Editor ，无论是 Windows 系统还是 OS X 系统，都要求电脑中首先要有 Node ，如果你的电脑中还没有 Node 环境，那么请先安装 Node 。

Node.js 是一个基于 Chrome V8 引擎的 JavaScript 运行时环境，同时提供了前台界面和后台服务的支持，而 Swagger Editor 的运行首先需要一个 http 服务器，所以在正式安装 Swagger Editor 时，我们首先需要安装一个 http 服务器。

2.1 第一步：在 Node 环境中安装 Http 服务器

在 Node 环境中，提供了很多 http 服务器的支持，例如：Express 、 http server 等。针对 Swagger Editor 的特点和后台服务器的适用条件，这里我们采用 http server 来当做 Swagger Editor 的服务器支持。

至于为什么选择 http server 来做后台服务器，这是不属于本节所介绍的内容，希望同学们可以在课下了解原因。

我们使用一下命令来在 Node 环境中安装 Http Server 服务器：

  npm install ‐g http‐server

-g 表示全局安装 http-server 服务器，这样我们就可以不用专门去 http-server 服务器目录下启动该服务了。

我们看到如下提示信息就表明安装 http-server 服务器成功：

2.2 第二步：在 http server 服务器中安装运行 Swagger Editor

要想在 http server 服务器中安装 Swagger Editor ，需要我们首先将 Swagger Editor 的压缩包下载下来，这就相当于在安装 Swagger Codegen 时的 Jar 包。出于方便考虑，我将 Swagger Editor 的资源压缩包放到了我的 Git 上面，同学们可以通过访问以下链接获取：

https://github.com/SteafanMrZhou/MoocSwaggerWiki

在安装好 http server 服务器之后，我们将下载好的压缩包进行解压，在解压完成后我们输入以下命令来启动 Swagger Editor 服务：

  http-server swagger-editor

我们看到下图提示信息则表明 Swagger Editor 服务已经安装成功并成功运行：

3. 如何基于 Docker 环境安装 Swagger Editor

基于 Docker 环境来安装 Swagger Editor 是 Swagger Editor 官方提供的第二种方式，同样地，想在 Docker 中安装 Swagger Editor ，需要电脑中首先要有 Docker 环境。

关于 Docker 的安装过程以及基础知识，由于不是本节文章所需要介绍的内容，所以该方面的知识点希望同学们可以在课下了解。

3.1 第一步 拉取 Swagger Editor Docker Image 镜像

众所周知，Docker 是一个容器服务，其是通过提供众多工具的镜像文件来将对应的服务集成到容器中，而且 Docker 官方整理了全球主流工具的镜像文件，并且将其放到了 DockerHub 上面。

所以，要想在 Docker 中安装 Swagger Editor ，我们首先需要从 Docker 官方的 DockerHub 上面将 Swagger Editor 的镜像文件拉取(下载)下来，在 Docker 容器中命令如下：

  docker pull swaggerapi/swagger-editor

运行以上指令，等待 Swagger Editor 的镜像文件拉取完毕。

3.2 第二步 在 Docker 中安装并运行 Swagger Editor

在 Swagger Editor 镜像拉取完毕之后，我们可以直接运行该镜像文件，如果运行成功，则表明 Swagger Editor 在Docker 环境中已经安装成功，运行 Swagger Editor 镜像文件的命令如下：

docker run -d -p 80:8080 swaggerapi/swagger-editor

代码解释：

docker run -d -p 为固定写法，同学们目前不用知道表示什么意思，只需要知道这是运行镜像文件的固定命令即可。

80:8080 表示将 Docker 容器中的 Swagger Editor 服务映射到我们本机的 80 端口上，

swaggerapi/swagger-editor 表明我们所运行的镜像文件的名称。

在运行 Swagger Editor 服务时，如果已经提供了 json 文件，那么我们可以使用以下命令进行启动，从而修改该 json 文件：

docker run -d -p 80:8080 -v $(pwd):/tmp -e SWAGGER_FILE=/tmp/swagger.json swaggerapi/swagger-editor

在运行上述指令后，我们等待 Swagger Editor 镜像文件在 Docker 容器中运行完毕即可。

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

无论使用哪种环境安装的 Swagger Editor ，检测安装是否成功的标志已经在上述内容中提及，接下来我们需要做的是访问我们已经安装并运行的 Swagger Editor 服务。

一般而言，当我们的 Swagger Editor 服务启动之后，可以通过以下方式来访问：

  http://localhost

如果在启动 Swagger Editor 服务的时候，你自定了服务的端口，则要通过以下方式来访问：

  http://localhost:8080(端口号)

在浏览器中输入访问地址之后，我们可以看到如下 Swagger Editor 的引导界面就表明 Swagger Editor 已经成功安装并且可以正常使用了：

Tips :

1. 在安装 Swagger Editor 之前，都需要我们首先将 Node 环境和 Docker 环境安装好，这是使用 Swagger Editor 的前提，在安装 Node 环境和 Docker 环境时，一定要注意版本的差异，一本推荐使用最新版本来安装

2. 一般在使用 Swagger Editor 的时候，很多情况都需要我们从零开始配置我们的 API 配置文件，很少情况会在基于已经配置好的 API 配置文件上进行修改。

3. 由于种种原因导致安装 Swagger Editor 失败的同学，可以通过访问 Swagger 官方提供的 Swagger Editor 在线使用地址(https://editor.swagger.io/)来了解 Swagger Editor：

5.小结

本小节针对当下主流环境，分别详细介绍了在 Node 环境和 Docker 环境中安装 Swagger Editor 的步骤，以及在安装时候容易出现的问题，针对 Swagger Editor 所需的压缩文件，考虑到自行下载可能下不动的情况，所以又额外提供了相关资源连接，同学们可以直接下载。

在安装 Swagger Editor 时，由于用到了 Node 环境和 Docker 环境，所以需要同学们先了解一下上述环境的基本使用方法，这样才可以随心应手的使用 Swagger Editor。

SpringBoot 集成 Swagger Editor

1. 前言

本节会为大家介绍，如何基于 Spring Boot 集成 Swagger Editor 到我们的项目中去，以及 Swagger Editor 快速入门相关知识点，希望通过本节讲解，大家可以对 Swagger Editor 有进一步的认识。

重点讲解内容：

• 如何将 Swagger Editor 集成到 SpringBoot 中去；

• Swagger Editor 快速入门与使用技巧。

2. 如何将 Swagger Editor 集成到 SpringBoot 中去 ？

集成前的问题

因为本套课程使用 Maven 包管理工具构建，所以在集成之前需要我们先将 Swagger Editor 的依赖引入到项目中去，但是很不幸，Swagger Editor 官方并没有提供对 Maven 的支持，所以我们就不能通过 Maven 的方式将 Swagger Editor 集成进来。

难道就没有办法将 Swagger Editor 与 SpringBoot 结合使用了吗 ？

俗话说，方法总比困难多，所以这里我们另辟蹊径，通过使用配置 yml 文件的方式将 Swagger Editor 集成进来，话不多说，我们直入正题。

2.1 第一步：修改 SpringBoot 项目配置文件

我们都知道，在 SpringBoot 项目中，一般的项目配置文件是如下图所示的 applicaiton.properties 文件：

applicaiton.properties 文件是传统的项目配置文件，无论使用 Spring 的哪种框架，我们都可以在项目中使用 applicaiton.properties 文件，但是这种文件有一种弊端，就是我们项目的配置信息在该文件中显示的有点乱，不利于开发人员维护，通常一行配置语句会显得很长，降低了项目配置文件的可阅读性。

正如此，在经过时代变迁之后，终于迎来了 YAML 配置源文件的到来，YAML 文件不单单只是一种平台上的配置源文件，他可以支持 Java 、 Python 、 PHP 等主流语言使用，并且各种语言平台都有对应的转换配置语法对应关系表，编写起来简单方便，且利于阅读。

将 applicaiton.properties 文件 修改为 YMAL 配置源文件的方式非常简单，我们只需要将 applicaiton.properties 文件的后缀 .properties 修改为 .yml 就可以了。

在修改完之后，我们就不能使用 applicaiton.properties 文件的语法了，我们需要使用 YMAL 配置源文件的语法才行。

2.2 第二步：配置 Swagger Editor 源文件

在集成 Swagger Editor 到 SpringBoot 中时，为什么我们需要将 SpringBoot 项目的配置文件 applicaiton.properties 来修改成 YAML 配置源文件呢 ？这是因为我们的 Swagger Editor 只支持以 .yml 文件格式结尾的配置文件来编写 Swagger Editor ，这也是我一再强调 YAML 配置源文件的原因。

在修改好配置源文件之后，接下来我们需要编写配置源文件，并且在编写完配置源文件之后，我们需要将该配置源文件进行重命名，重命名的规则一般都是项目名称 + Swagger Editor + 配置源文件版本号。

简易配置 Swagger Editor 源文件

Swagger Editor 的配置源文件我们在 Spring Boot 集成 Swagger Codegen 小节中做了简短的介绍：就是我们在配置 Swagger Codegen 服务端代码生成规则那里的服务端代码其实就是 Swagger Editor 配置源文件的一部分，也就是说Swagger Codegen 服务端的代码生成规则是通过 Swagger Editor 配置源文件来实现的。

所以，在掌握了 Swagger Editor 的基本语法和使用技巧之后，我们就可以在编写好 Swagger Editor 配置源文件之后来生成我们项目的服务端代码，可谓是一举两得，这也是 Swagger 官方为我们所考虑的一方面。

还是那句话，在 Swagger Editor 中，配置 Swagger Editor 需要对 yml 配置源文件有一定的了解和使用，所以，有不清楚的同学请自行查阅相关资料。

接下来我们通过 Swagger Editor 官方的 Demo 来为大家配置 Swagger Editor 。

Swagger Editor 基本配置信息

swagger: "2.0"
info:
 description: "This is a sample server Petstore server. You can find out more about Swagger at http://swagger.io or on irc.freenode.net, #swagger. For this sample, you can use the api key special-key to test the authorization filters."
 version: "1.0.0"
 title: "Swagger Petstore"
 termsOfService: "http://swagger.io/terms/"
 contact:
   email: "apiteam@swagger.io"
 license:
   name: "Apache 2.0"
   url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "petstore.swagger.io"
basePath: "/v2"
tags:
 name: "pet"
 description: "Everything about your Pets"
 externalDocs:
 description: "Find out more"
 url: "http://swagger.io"
schemes:
 "https"
 "http"

Swagger Editor 接口配置信息

paths:
  /pet:
    post:
      tags:
       - "pet"
      summary: "Add a new pet to the store"
      description: ""
      operationId: "addPet"
      consumes:
        "application/json"
        "application/xml"
      produces:
        "application/xml"
        "application/json"
      parameters:
        in: "body"
        name: "body"
        description: "Pet object that needs to be added to the store"
        required: true
        schema:
          $ref: "#/definitions/Pet"
    responses:
      "405":
        description: "Invalid input"

对于以上所使用的属性我们会在本节的后半部分进行详细介绍，这里大家可以先做简单的了解即可。

2.3 第三步：使用 Swagger Editor 生成 Swagger-UI 界面

在配置好 Swagger Editor 基本配置信息和 Swagger Editor 接口配置信息之后，我们就可以在项目中生成 Swagger-UI 界面了。

我们生成 Swagger-UI 界面需要依赖 http-server ，我们在编辑器的控制台中输入以下命令即可：

  http-server swagger-editor .yml文件路径

即我们为 Swagger Editor 指定需要使用的 .yml 配置源文件即可，生成后的界面如下图所示。

3. Swagger Editor 快速入门与使用技巧

接下来，我们针对上述 Swagger Editor 配置源文件中的属性来为大家介绍每个属性都代表什么意思，都用来做什么，以及在使用 Swagger Editor 时的一些使用技巧和注意事项。

3.1 Swagger Editor 快速入门

Swagger Editor 基本配置信息

swagger: "2.0"
info:
  description: "Swagger Editor Demo"
  version: "1.0.0"
  title: "Swagger Petstore"
  termsOfService: "http://swagger.io/terms/"
  contact:
    email: "apiteam@swagger.io"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "petstore.swagger.io"
basePath: "/v2"
tags:
  name: "pet"
  description: "Everything about your Pets"
  externalDocs:
  description: "Find out more"
  url: "http://swagger.io"
schemes:
  "https"
  "http"

代码解释：

swagger : 指名所使用的 Swagger 管理版本，这里只能写 2.0 。

info : 表示 Swagger Codegen 所生成的 Swagger-UI 界面的一些基本描述信息，上述包括 title(头信息) 、 description(文档描述) 、 version(文档版本) 、termsOfService(服务团队) 、 contact(联系人) 、 license(协议或条款)。

host : 表示生成的 Swagger-UI 所在的主机，即 Swagger-UI 界面生成之后是放在什么位置的。

basePath : 表示访问 Swagger-UI 生成界面的具体路径。

tags : 表示对 Swagger-UI 文档中的接口进行分组。

tags-description : 对接口分组添加描述信息。

tags-externalDocs : 指定接口分组额外的说明文档，这里没有指定。

tags-url : 表示对该接口分组添加额外的描述信息地址。

schemes : 表示整个 Swagger-UI 界面上的接口所使用的网络协议，这里指名可以使用 http 和 https 网络协议。

Swagger Editor 接口配置信息

由于篇幅有限，Swagger Editor 接口配置信息部分的属性介绍在 SpringBoot 集成 Swagger Codegen 这一小节中有详细的说明，同学们可以去该小节了解。

3.2 Swagger Editor 使用技巧

我们在使用 Swagger Editor 时，一般都是在没有借口文档的情况下进行，所以这就要求我们对接口所开展的业务有很清晰的了解才行。

在 Swagger Editor 中，我们会对不同属性编写不同的描述信息，而涉及到名字的属性一定要注意，例如：title 属性，在对这一类型属性进行描述时，我们应该根据项目需求文档来进行描述，不能自己随意起名字，只有按照项目需求文档来描述的 Swagger Editor 属性才能说是准确的，是服务于当前项目的。

即使我们把 Swagger Editor 引入到了 SpringBoot 项目中去，但是如果想要运行 Swagger Editor ，我们还是要依赖于 http-server ，因为 Maven 并没有提供对 Swagger Editor 的支持服务。

4.小结

本小节对在基于 SpringBoot 环境下如何集成 Swagger Editor 进行了详细的介绍，通过对分解的集成实现思路的详细介绍以及为何要采用该种实现思路的原因都做了详细的介绍和补充说明，在文章最后还详细阐述了 Swagger Editor 在实际项目开发中使用的一些注意事项，旨在帮助大家在了解了 Swagger Editor 基本定义之后可以快速入门 Swagger Editor。

在集成 Swagger Editor 时，还需要注意 Swagger Editor 与 Swagger Codegen 之间的共同点与不同点，注意区分和体会他们的应用场景和使用目的，这样在实际开发中才能根据不同场景来选择合适的工具来完成工作。

Swagger Validator、Parser、Inflector 简介

1. 前言

大家好，今天为大家介绍 Swagger 生态体系中的最后一部分内容- Swagger 辅助工具。该部分内容主要介绍 Swagger 官方提供的辅助工具，他们分别是：Validator、Parser、Inflector。

在本节中我会对这三个辅助工具进行一些简单必要的介绍，由于篇幅原因，不会详细介绍他们应该怎么用，如有需要请自行查阅相关资料。

本节主要内容如下：

• Swagger Validator 的定义及简单使用；

• Swagger Parser 的定义及简单使用；

• Swagger Inflector 的定义及简单使用。

2. Swagger Validator 的定义及简单使用

2.1 什么是 Swagger Validator ？

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

Swagger Validator 是一个 Swagger 验证器，用于验证你的 Swagger 文档。    —官网

我们来看一下 Swagger Validator 官方提供的一款在线体验平台(https://validator.swagger.io/)：

从图中我们可以看到，Swagger Validator 的显示界面非常类似于 Swagger-UI 的显示界面，风格和排版都很相似，那么我们应该怎么来用呢 ？

2.2 Swagger Validator 的简单使用

根据官方文档我们不难看出，Swagger Validator 就是一个校验 Swagger 文档的工具，那么我们应该怎么来用呢 ？

我们可以在上述截图中看到一个 Validator 字样的单词，在这个单词下放，是 Swagger 官方为我们提供的 Swagger 文档中接口请求规范，以及接口定义要求。

就是说，我们可以把我们编写的 Swagger 文档和 Swagger Validator 官方校验界面做一个比较，看一下是否符合 Swagger Validator 官方的要求，校验的范围就包括：接口请求定义是否符合规范、接口返回值是否符合规范等，而进行校验的方式就是通过对比 Validator 下的内容。

如果在校验后发现，我们的 Swagger 文档有部分内容不符合 Swagger Validator 官方所展示的，那么我们就需要对这一部分进行修改，直至符合 Swagger Validator 官方的要求才行。

3. Swagger Parser 的定义及简单使用

3.1 什么是 Swagger Parser ？

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

Swagger Parser 是可以将 Java 项目中的 POJO 文件都解析成符合 OpenAPI 规范的类，同时它也提供了一个简单的框架来将不同平台的 POJO 文件都转换为统一的 Swagger 对象，来使整个 Swagger 工具链变得可用。    —官网

我们可以这样简单的理解：Swagger Parser 是专门服务于 POJO 文件的一个工具包，他可以将来自不同平台中的不符合 OpenAPI 规范的 POJO 文件都解析成符合统一规范的格式，使得我们在任何平台上都可以正常的使用 Swagger 。

3.2 Swagger Parser 的简单使用

由于 Maven 官方提供了对 Swagger Parser 的支持，所以我们只要将 Swagger Parser 的 Maven 依赖引入到我们项目中去就可以使用了：

  <dependency>
      <groupId>io.swagger.parser.v3</groupId>
      <artifactId>swagger-parser</artifactId>
      <version>2.0.20</version>
  </dependency>

通过配置以下代码我们就可以来读取符合 OpenAPI 规范的文件了:

    import io.swagger.v3.parser.OpenAPIV3Parser;
    import io.swagger.v3.oas.models.OpenAPI;


    OpenAPI openAPI = new OpenAPIV3Parser().read("https://petstore3.swagger.io/api/v3/openapi.json");

• 第1-2行，我们在项目中引入使用 Swagger Parser 必须的包。

• 第3-4行，我们使用 read 方法来读取 Swagger 官方的符合 OpenAPI 规范的文件。

4. Swagger Inflector 的定义及简单使用

4.1 什么是 Swagger Inflector ？

什么是 Swagger Inflector 呢？在 Swagger 官网中是这么介绍的(由于介绍太长，这里只选择主要部分说明)：

Swagger Inflector 是可以使用 Swagger 规范去驱动一种 API 的实现，并且你拥有全部的权限在实现过程中进行修改。    —官网

也就是说，Swagger Inflector 是一款可以使用 Swagger 规范去生成符合 Swagger 规范的 API 工具，并且可以在实现过程中针对不符合规范的地方进行完全的修改，最后使之符合 Swagger 的规范。

4.2 Swagger Inflector 的简单使用

由于 Swagger Inflector 的使用相对非常少，并且如果想使用 Swagger Inflector ，那么你的项目就必须使用一种框架才能将 Swagger Inflector 集成进去，这个框架就是 Jersey 。

关于 Jersey ，这里就不多说了，大家只需要这是一款小众框架就行了，现在没有完全被淘汰，还有很多小公司仍在使用。

那么，在将 Jersey 集成好之后，我们就可以在 Jersey 生成的 web.xml 文件中添加如下配置来使用 Swagger Inflector 了：

 <servlet>
   <servlet-name>swagger-inflector</servlet-name>
   <servlet-class>
       org.glassfish.jersey.servlet.ServletContainer
   </servlet-class>
   <init-param>
   <param-name>javax.ws.rs.Application</param-name>
   <param-value>
       io.swagger.oas.inflector.OpenAPIInflector
   </param-value>
   </init-param>
   <load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
   <servlet-name>swagger-inflector</servlet-name>
   <url-pattern>/*</url-pattern>
</servlet-mapping>

Tips :

1. Swagger Validator 、Parser 、Inflector 都是 Swagger 官方提供的辅助工具，主要目的都是为了使 Swagger 相关文件更符合 Swagger 的规范，这三个工具他们各司其职，同学们在使用时注意区分适用场景。

2. 这三个辅助工具虽然在实际项目开发中很少使用，但是他们也属于 Swagger 整个系统中的一部分内容，所以要想系统学号和用好 Swagger ，那么该部分内容是不可获取的。

5. 小结

我们在学习 Swagger Validator 、Parser 、Inflector 时一定要注意他们的适用场景，区分他们之间的共同点和不同点，在学习本节内容时自己可以动手实践一下，这样才能更好地掌握。

Swagger Validator 、Parser 、Inflector 这三款辅助工具的介绍作为 Swagger 整套课程体系的最后一节内容，老师从他们的不同使用业务场景出发，介绍了他们最简单的使用方法，希望通过本节内容的介绍，同学们可以对这三款辅助工具有一个新的认识。

同学们，写到这里，Swagger 系统知识点就给各位介绍完毕了，在这中间感谢各位的支持，江湖路远，我们有缘再见！

上一节