Swagger Validator、Parser、Inflector 簡(jiǎn)介

1. 前言

大家好，今天為大家介紹 Swagger 生態(tài)體系中的最后一部分內(nèi)容- Swagger 輔助工具。該部分內(nèi)容主要介紹 Swagger 官方提供的輔助工具，他們分別是：Validator、Parser、Inflector。

在本節(jié)中我會(huì)對(duì)這三個(gè)輔助工具進(jìn)行一些簡(jiǎn)單必要的介紹，由于篇幅原因，不會(huì)詳細(xì)介紹他們應(yīng)該怎么用，如有需要請(qǐng)自行查閱相關(guān)資料。

本節(jié)主要內(nèi)容如下：

• Swagger Validator 的定義及簡(jiǎn)單使用；

• Swagger Parser 的定義及簡(jiǎn)單使用；

• Swagger Inflector 的定義及簡(jiǎn)單使用。

2. Swagger Validator 的定義及簡(jiǎn)單使用

2.1 什么是 Swagger Validator ？

什么是 Swagger Validator 呢？在 Swagger 官網(wǎng)中是這么介紹的：

Swagger Validator 是一個(gè) Swagger 驗(yàn)證器，用于驗(yàn)證你的 Swagger 文檔。 —官網(wǎng)

我們來(lái)看一下 Swagger Validator 官方提供的一款在線體驗(yàn)平臺(tái)(https://validator.swagger.io/)：

從圖中我們可以看到，Swagger Validator 的顯示界面非常類似于 Swagger-UI 的顯示界面，風(fēng)格和排版都很相似，那么我們應(yīng)該怎么來(lái)用呢 ？

2.2 Swagger Validator 的簡(jiǎn)單使用

根據(jù)官方文檔我們不難看出，Swagger Validator 就是一個(gè)校驗(yàn) Swagger 文檔的工具，那么我們應(yīng)該怎么來(lái)用呢 ？

我們可以在上述截圖中看到一個(gè) Validator 字樣的單詞，在這個(gè)單詞下放，是 Swagger 官方為我們提供的 Swagger 文檔中接口請(qǐng)求規(guī)范，以及接口定義要求。

就是說(shuō)，我們可以把我們編寫(xiě)的 Swagger 文檔和 Swagger Validator 官方校驗(yàn)界面做一個(gè)比較，看一下是否符合 Swagger Validator 官方的要求，校驗(yàn)的范圍就包括：接口請(qǐng)求定義是否符合規(guī)范、接口返回值是否符合規(guī)范等，而進(jìn)行校驗(yàn)的方式就是通過(guò)對(duì)比 Validator 下的內(nèi)容。

如果在校驗(yàn)后發(fā)現(xiàn)，我們的 Swagger 文檔有部分內(nèi)容不符合 Swagger Validator 官方所展示的，那么我們就需要對(duì)這一部分進(jìn)行修改，直至符合 Swagger Validator 官方的要求才行。

3. Swagger Parser 的定義及簡(jiǎn)單使用

3.1 什么是 Swagger Parser ？

什么是 Swagger Parser 呢？在 Swagger 官網(wǎng)中是這么介紹的：

Swagger Parser 是可以將 Java 項(xiàng)目中的 POJO 文件都解析成符合 OpenAPI 規(guī)范的類，同時(shí)它也提供了一個(gè)簡(jiǎn)單的框架來(lái)將不同平臺(tái)的 POJO 文件都轉(zhuǎn)換為統(tǒng)一的 Swagger 對(duì)象，來(lái)使整個(gè) Swagger 工具鏈變得可用。 —官網(wǎng)

我們可以這樣簡(jiǎn)單的理解：Swagger Parser 是專門服務(wù)于 POJO 文件的一個(gè)工具包，他可以將來(lái)自不同平臺(tái)中的不符合 OpenAPI 規(guī)范的 POJO 文件都解析成符合統(tǒng)一規(guī)范的格式，使得我們?cè)谌魏纹脚_(tái)上都可以正常的使用 Swagger 。

3.2 Swagger Parser 的簡(jiǎn)單使用

由于 Maven 官方提供了對(duì) Swagger Parser 的支持，所以我們只要將 Swagger Parser 的 Maven 依賴引入到我們項(xiàng)目中去就可以使用了：

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

通過(guò)配置以下代碼我們就可以來(lái)讀取符合 OpenAPI 規(guī)范的文件了:

    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行，我們?cè)陧?xiàng)目中引入使用 Swagger Parser 必須的包。

• 第3-4行，我們使用 read 方法來(lái)讀取 Swagger 官方的符合 OpenAPI 規(guī)范的文件。

4. Swagger Inflector 的定義及簡(jiǎn)單使用

4.1 什么是 Swagger Inflector ？

什么是 Swagger Inflector 呢？在 Swagger 官網(wǎng)中是這么介紹的(由于介紹太長(zhǎng)，這里只選擇主要部分說(shuō)明)：

Swagger Inflector 是可以使用 Swagger 規(guī)范去驅(qū)動(dòng)一種 API 的實(shí)現(xiàn)，并且你擁有全部的權(quán)限在實(shí)現(xiàn)過(guò)程中進(jìn)行修改。 —官網(wǎng)

也就是說(shuō)，Swagger Inflector 是一款可以使用 Swagger 規(guī)范去生成符合 Swagger 規(guī)范的 API 工具，并且可以在實(shí)現(xiàn)過(guò)程中針對(duì)不符合規(guī)范的地方進(jìn)行完全的修改，最后使之符合 Swagger 的規(guī)范。

4.2 Swagger Inflector 的簡(jiǎn)單使用

由于 Swagger Inflector 的使用相對(duì)非常少，并且如果想使用 Swagger Inflector ，那么你的項(xiàng)目就必須使用一種框架才能將 Swagger Inflector 集成進(jìn)去，這個(gè)框架就是 Jersey 。

關(guān)于 Jersey ，這里就不多說(shuō)了，大家只需要這是一款小眾框架就行了，現(xiàn)在沒(méi)有完全被淘汰，還有很多小公司仍在使用。

那么，在將 Jersey 集成好之后，我們就可以在 Jersey 生成的 web.xml 文件中添加如下配置來(lái)使用 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 相關(guān)文件更符合 Swagger 的規(guī)范，這三個(gè)工具他們各司其職，同學(xué)們?cè)谑褂脮r(shí)注意區(qū)分適用場(chǎng)景。
2. 這三個(gè)輔助工具雖然在實(shí)際項(xiàng)目開(kāi)發(fā)中很少使用，但是他們也屬于 Swagger 整個(gè)系統(tǒng)中的一部分內(nèi)容，所以要想系統(tǒng)學(xué)號(hào)和用好 Swagger ，那么該部分內(nèi)容是不可獲取的。

5. 小結(jié)

我們?cè)趯W(xué)習(xí) Swagger Validator 、Parser 、Inflector 時(shí)一定要注意他們的適用場(chǎng)景，區(qū)分他們之間的共同點(diǎn)和不同點(diǎn)，在學(xué)習(xí)本節(jié)內(nèi)容時(shí)自己可以動(dòng)手實(shí)踐一下，這樣才能更好地掌握。

Swagger Validator 、Parser 、Inflector 這三款輔助工具的介紹作為 Swagger 整套課程體系的最后一節(jié)內(nèi)容，老師從他們的不同使用業(yè)務(wù)場(chǎng)景出發(fā)，介紹了他們最簡(jiǎn)單的使用方法，希望通過(guò)本節(jié)內(nèi)容的介紹，同學(xué)們可以對(duì)這三款輔助工具有一個(gè)新的認(rèn)識(shí)。

同學(xué)們，寫(xiě)到這里，Swagger 系統(tǒng)知識(shí)點(diǎn)就給各位介紹完畢了，在這中間感謝各位的支持，江湖路遠(yuǎn)，我們有緣再見(jiàn)！