亚洲在线久爱草,狠狠天天香蕉网,天天搞日日干久草,伊人亚洲日本欧美

Steafan_ · 更新于 2020-08-25

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 系統知識點就給各位介紹完畢了，在這中間感謝各位的支持，江湖路遠，我們有緣再見！