Swagger 簡介

1. 前言

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

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

本文我們主要先介紹一下 Swagger 是什么？有哪些特性？優(yōu)缺點在哪？為什么我們需要在項目開發(fā)中應(yīng)用 Swagger ？

2. 什么是 Swagger ？

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

Swagger 就是一種可以幫助我們簡化 API 開發(fā)過程的工具。 — 官網(wǎng)

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

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

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

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

3. 為什么要使用 Swagger ？

那么我們?yōu)槭裁匆褂?Swagger 呢？

3.1 配置簡單，容易上手

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

3.2 界面美觀，便于理解

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

3.3 交互方便，完善溝通

我們在開發(fā) Java 項目的時候，主要的目的就是對外暴露我們的數(shù)據(jù)傳輸接口，來實現(xiàn)前后臺數(shù)據(jù)交互的目的。

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

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

總結(jié)：

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

4. Swagger 的版本說明

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

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

5. Swagger 的優(yōu)點

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

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

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

6. Swagger 的缺點

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

7. 學(xué)習(xí)基礎(chǔ)

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

8. 小結(jié)

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