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

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

1、Swagger簡介

記得多年以前，在Swagger還沒有出現的時候，我還用自己手寫的Maven插件，來實現自動生成API的功能。界面有點丑，給大家秀一下：

當時，還想著開源，后來Swagger問世之后，我就把源碼從github上下了。

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

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

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

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

2、為什么要使用 Swagger

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

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

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

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

3）提供交互式的UI，我們可以直接在文檔頁面調試 API，省去了準備復雜的調試參數的過程。

4）還可以將文檔導入到自動化測試工具中，快速生成測試報告。

3、Swagger工作流程

Swagger接口生成工作流程：

1、系統啟動時，掃描Swagger的配置類

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

比如：配置發(fā)送錯誤返回的信息 @ApiError ，配置一個或者多個請求參數，@ApiImplicitParam、@ApiImplicitParams等等。

3、根據Controller類中的Swagger注解生成接口文檔，啟動項目，訪問項目虛擬路徑/swagger-ui，查看生成的文檔內容。