現(xiàn)在的Java開發(fā)，一般都會(huì)用到API生成工具Open API，今天一位工作2年的小伙伴突然被問到Swagger工作流程，一下子無言以對(duì)。于是，來找到我，希望我能科普一下。

今天，我給大家分享一下我的理解。

1、Swagger簡(jiǎn)介

記得多年以前，在Swagger還沒有出現(xiàn)的時(shí)候，我還用自己手寫的Maven插件，來實(shí)現(xiàn)自動(dòng)生成API的功能。界面有點(diǎn)丑，給大家秀一下：

當(dāng)時(shí)，還想著開源，后來Swagger問世之后，我就把源碼從github上下了。

Swagger 是一套基于 OpenAPI 規(guī)范構(gòu)建的開源工具，可以幫助我們?cè)O(shè)計(jì)、構(gòu)建、記錄以及使用 Rest API。Swagger 主要包含了以下三個(gè)部分：

Swagger Editor：基于瀏覽器的編輯器，我們可以使用它編寫我們 OpenAPI 規(guī)范。

Swagger UI：它會(huì)將我們編寫的 OpenAPI 規(guī)范呈現(xiàn)為交互式的 API 文檔。

Swagger Codegen：它可以通過為 OpenAPI規(guī)范定義的任何 API 生成服務(wù)器存根和客戶端 SDK 來簡(jiǎn)化構(gòu)建過程。

2、為什么要使用 Swagger

在前后端分離開發(fā)以后，維持一份及時(shí)更新且完整的 Rest API 文檔，能夠極大的提高的開發(fā)效率。傳統(tǒng)意義上的文檔都是后端開發(fā)人員手動(dòng)編寫的，一般是以Doc或者是md等形式離線傳播。而在開發(fā)階段，接口修改非常頻繁，就很難保證文檔更新的及時(shí)性，久而久之就失去了參考意義，反而還會(huì)加大團(tuán)建之間的溝通成本。

而 Swagger 給我們提供了一個(gè)全新的維護(hù) API 文檔的方式，只要項(xiàng)目發(fā)布，就能夠自動(dòng)更新，而且可以同步到線上，使用者只需要記住一個(gè)固定的網(wǎng)址，實(shí)時(shí)刷新就能訪問到最新版本的API文檔了。下面我總結(jié)一下Swagger的主要優(yōu)點(diǎn)：

1）代碼變，文檔變。只需要少量的注解，Swagger 就可以根據(jù)代碼自動(dòng)生成 API 文檔，很好的保證了文檔的時(shí)效性。

2）跨語言性，支持 40 多種語言。

3）提供交互式的UI，我們可以直接在文檔頁面調(diào)試 API，省去了準(zhǔn)備復(fù)雜的調(diào)試參數(shù)的過程。

4）還可以將文檔導(dǎo)入到自動(dòng)化測(cè)試工具中，快速生成測(cè)試報(bào)告。

3、Swagger工作流程

Swagger接口生成工作流程：

1、系統(tǒng)啟動(dòng)時(shí)，掃描Swagger的配置類

2、在此類中指定來要掃描的包路徑，找到在此包下及子包下標(biāo)記@RestController注解的Controller類。還可以通過以下這些注解來靈活配置一些參數(shù)。

比如：配置發(fā)送錯(cuò)誤返回的信息 @ApiError ，配置一個(gè)或者多個(gè)請(qǐng)求參數(shù)，@ApiImplicitParam、@ApiImplicitParams等等。

3、根據(jù)Controller類中的Swagger注解生成接口文檔，啟動(dòng)項(xiàng)目，訪問項(xiàng)目虛擬路徑/swagger-ui，查看生成的文檔內(nèi)容。

網(wǎng)站題目：談?wù)勀銓?duì)Swagger工作流程的理解？
鏈接地址：http://uogjgqi.cn/article/djghggs.html