跳到主要内容

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 系统知识点就给各位介绍完毕了，在这中间感谢各位的支持，江湖路远，我们有缘再见！