Swagger 簡介

1. 前言

大家好，今天我們開始一個新專題 — Swagger。

關于 Swagger 相信我們都在實際項目開發中使用過，它的核心知識點完全可以整理成一組專題來展開介紹，本專題我們重點講解 Swagger 在基于 Java 生態框架的日常開發過中如何來應用。

本文我們主要先介紹一下 Swagger 是什么？有哪些特性？優缺點在哪？為什么我們需要在項目開發中應用 Swagger ？

2. 什么是 Swagger ？

什么是 Swagger 呢？在 Swagger 官網中是這么介紹的：

Swagger 就是一種可以幫助我們簡化 API 開發過程的工具。 — 官網

我們看到，這里提到了 API 這一術語，在業界，API 一般指的是：通過后端編碼而開發出來的，且可以供其他用戶所使用的一種專門對外暴露的數據傳輸接口，即我們可以通過編寫 API 來達到和用戶交互的目的。俗話說無規矩不成方圓，針對 API 業界也制定了一款標準，那就是 RESTFUL API 規范，下面我們來簡單介紹一下什么是 RESTFUL API 規范：

RESTFUL 的全稱是 Representational State Transfer，即表述性狀態轉換，或者我們可以通俗的理解為：一組具有約束條件和原則的規范。

也就是說：RESTFUL API 就是經過一組確定好的具有約束行為和統一原則的規范來規定 API 書寫規則、命名規則、請求規則、響應規則的一種表述性方式。通過這個方式我們可以很好地理解具體 API 所代表的的業務場景和返回字段的含義。

通過上面的介紹，說白了，Swagger 就是一款可以簡化項目 API 開發的工具，用來幫助我們通過最簡單的途徑來開發 RESTFUL API。

3. 為什么要使用 Swagger ？

那么我們為什么要使用 Swagger 呢？

3.1 配置簡單，容易上手

如果我們需要在項目中使用 Swagger，那么我們只需要將 Swagger 的依賴集成到項目中去，然后通過一個簡單的 Swagger 配置類即可開始使用了，不需要像其他工具那樣還要繁瑣的去配置 xml，即配置簡單，容易上手。這為我們節省了大量的時間，使得我們可以把時間用在集中處理項目業務上，提升我們的開發效率。

3.2 界面美觀，便于理解

Swagger 通過內置 html 解析器的方式來實現將 RESTFUL API 顯示在界面上供開發者查看，Swagger 提供的界面樣式即簡潔又美觀，開發者可以很直觀地看到自己所編寫的 RESTFUL API 的請求方式、請求參數、返回格式以及所屬業務組，如下圖所示。

3.3 交互方便，完善溝通

我們在開發 Java 項目的時候，主要的目的就是對外暴露我們的數據傳輸接口，來實現前后臺數據交互的目的。

針對于我們編寫的接口，往往我們需要撰寫接口文檔來說明具體接口所做的業務是什么，以及這個接口如何使用。這樣在無形之中就加重了我們的工作內容，而有了 Swagger 之后，我們只需要在相應的地方添加 Swagger 的注解來對接口進行簡單的說明，它就會幫助我們生成一份完整的接口說明，見上圖。

這樣一來我們就不用再編寫一份幾十頁甚至幾百頁的接口文檔了，提升了交互性能，同時也提升了前后臺開發者的溝通效率。

總結：

Swagger 它是一個幫助開發人員來簡化開發 RESTFUL API 的一款開發工具，其核心是基于 NPM 實現，在 Spring 項目中則是通過封裝 SpringFox 依賴來完成對接口請求方式、請求參數、響應數據的加載，最終通過前端界面的方式來展現給用戶。Swagger 具有簡單、方便、高效的特性，用 Swagger 構建 RESTFUL API 可快速又方便。

4. Swagger 的版本說明

Swagger 從 2011 年發布至今已經有 9 個年頭，期間已經迭代升級了很多版本，現在最新的版本是 v3.18.3，每個版本都有不同的特性，下面主要介紹一個主要使用的版本和新版本的特性。

• V1.0.1 - 1.0.13： 最初發布版本，基本已經很少使用了。
• V2.X.X: 目前使用較多的版本，也是我們這個課程使用的版本。
• V3.18.3: 目前發布的最新版本，2018 年 8 月 3 日發布的。主要是優化了接口組的使用方法、美化了 RESTFUL API 界面顯示效果。最新版本可能會導致部分項目無法正常使用，這個時候需要回退到 2.X.X 版本即可。

5. Swagger 的優點

• 導出格式靈活 : 支持 Json 和 yml 來編寫 API 文檔，并且支持導出為 json、yml、markdown 等格式。

• 跨語言支持性 : 只針對 API，而不針對特定語言的 API，很多自動生成 API 的工具基本都是只針對特定的 API。

• 界面清晰易懂 : 界面清晰，無論是 Editor 的實時展示還是 Swagg-UI 界面的展示都十分人性化，簡單明了。

6. Swagger 的缺點

• 無法自定義界面 : Swagger-UI 封裝好了一套 Html 模板，任何 RESTFUL API 的展示形式只能遵循其格式，不能靈活修改。
• 官方文檔不全面 : Swagger 官方針對不同的模塊提供了不同的介紹文檔，但是缺乏系統的介紹，不利于新人學習。

7. 學習基礎

學習這門課程首先要有基于 Java 生態框架開發項目的經驗，可以是使用 Java 框架開發項目的新人，也可以是具有豐富項目開發經驗的老司機。
本套課程是用 SpringBoot 的方式，通過 Maven 包管理工具來快速使用 SpringBoot 框架，所以沒有接觸過 SpringBoot 框架和 Maven 包管理工具的同學請自行了解。

8. 小結

本節是本套課程的開端，主要介紹了什么是 Swagger ，為什么使用 Swagger ，以及 Swagger 優缺點等。