Swagger 簡介

1. 前言

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

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

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

2. 什么是 Swagger ？

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

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

我們看到，這里提到了 API 這一術(shù)語，在業(yè)界，API 一般指的是：通過后端編碼而開發(fā)出來的，且可以供其他用戶所使用的一種專門對(duì)外暴露的數(shù)據(jù)傳輸接口，即我們可以通過編寫 API 來達(dá)到和用戶交互的目的。俗話說無規(guī)矩不成方圓，針對(duì) 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ī)則、請(qǐng)求規(guī)則、響應(yīng)規(guī)則的一種表述性方式。通過這個(gè)方式我們可以很好地理解具體 API 所代表的的業(yè)務(wù)場景和返回字段的含義。

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

3. 為什么要使用 Swagger ？

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

3.1 配置簡單，容易上手

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

3.2 界面美觀，便于理解

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

3.3 交互方便，完善溝通

我們?cè)陂_發(fā) Java 項(xiàng)目的時(shí)候，主要的目的就是對(duì)外暴露我們的數(shù)據(jù)傳輸接口，來實(shí)現(xiàn)前后臺(tái)數(shù)據(jù)交互的目的。

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

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

總結(jié)：

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

4. Swagger 的版本說明

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

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

5. Swagger 的優(yōu)點(diǎn)

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

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

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

6. Swagger 的缺點(diǎn)

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

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

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

8. 小結(jié)

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