今天技術總監說：小明，我們本次3.0改造，使用swagger2.0作為前后端分離的接口規范，它可以一鍵生成前后端的API,一勞永逸……小明：？？？

Spring Boot 框架是目前非常流行的微服務框架，我們很多情況下使用它來提供 Rest API，而對于 Rest API 來說很重要的一部分內容就是文檔，Swagger 為我們提供了一套通過代碼和注解自動生成文檔的方法，這一點對于保證 API 文檔的及時性將有很大的幫助。本文將使用 Swagger 2 規范的 Springfox 實現來了解如何在 Spring Boot 項目中使用 Swagger，主要包含了如何使用 Swagger 自動生成文檔、使用 Swagger 文檔以及 Swagger 相關的一些高級配置和注解。

Swagger 簡介

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

1. Swagger Editor：基于瀏覽器的編輯器，我們可以使用它編寫我們 OpenAPI 規范。
2. Swagger UI：它會將我們編寫的 OpenAPI 規范呈現為交互式的 API 文檔，后文我將使用瀏覽器來查看并且操作我們的 Rest API。
3. Swagger Codegen：它可以通過為 OpenAPI（以前稱為 Swagger）規范定義的任何 API 生成服務器存根和客戶端 SDK 來簡化構建過程。

為什么要使用 Swagger

當下很多公司都采取前后端分離的開發模式，前端和后端的工作由不同的工程師完成。在這種開發模式下，維持一份及時更新且完整的 Rest API 文檔將會極大的提高我們的工作效率。傳統意義上的文檔都是后端開發人員手動編寫的，相信大家也都知道這種方式很難保證文檔的及時性，這種文檔久而久之也就會失去其參考意義，反而還會加大我們的溝通成本。而 Swagger 給我們提供了一個全新的維護 API 文檔的方式，下面我們就來了解一下它的優點：

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

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

3. Swagger UI 呈現出來的是一份可交互式的 API 文檔，我們可以直接在文檔頁面嘗試 API 的調用，省去了準備復雜的調用參數的過程。

4. 還可以將文檔規范導入相關的工具（例如 SoapUI）, 這些工具將會為我們自動地創建自動化測試。

以上這些優點足以說明我們為什么要使用 Swagger 了，您是否已經對 Swagger 產生了濃厚的興趣了呢？下面我們就將一步一步地在 Spring Boot 項目中集成和使用 Swagger，讓我們從準備一個 Spring Boot 的 Web 項目開始吧。

準備 Spring Boot Web 項目

在這一步我們將準備一個基礎的 Spring Boot 的 Web 項目，并且提供后面所需要的所有 API。

創建一個空的 Spring Boot 項目

您可以通過 Spring Initializr 頁面生成一個空的 Spring Boot 項目，當然也可以下載 springboot-pom.xml 文件，然后使用 Maven 構建一個 Spring Boot 項目。項目創建完成后，為了方便后面代碼的編寫您可以將其導入到您喜歡的 IDE 中，我這里選擇了 Intelli IDEA 打開。

添加依賴

由于創建的是一個 Web 項目，所以我們需要依賴 Spring Boot 的 Web 組件，只需要在 pom.xml 增加如下內容即可：

清單 1. 添加 Web 依賴

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

編寫接口

1. 首先我們創建三個包：cn.itweknow.sbswagger.controller、cn.itweknow.sbswagger.testcontroller 以及 cn.itweknow.sbswagger.model。
2. 在 controller 包下新建 UserController.java 類，在 testcontroller 包下新建 TestController.java 類，在 model 包下新建 User.java 類。
3. UserController 提供用戶的增、刪、改、查四個接口，TestContrller 提供一個測試接口，這里粘上 UserController.java 的代碼，其余代碼可以查看源碼。

清單 2. UserController.java 代碼

@RestController
@RequestMapping("/user")
public class UserController {
    @PostMapping("/add")
    public boolean addUser(@RequestBody User user) {
        return false;
    }
    @GetMapping("/find/{id}")
    public User findById(@PathVariable("id") int id) {
        return new User();
    }
    @PutMapping("/update")
    public boolean update(@RequestBody User user) {
        return true;
    }
    @DeleteMapping("/delete/{id}")
    public boolean delete(@PathVariable("id") int id) {
        return true;
    }
}

集成 Swagger2

經過上面的步驟，我們已經擁有了五個接口，分別是:

1. /user/add：新增用戶。
2. /user/find/{id}：根據 id 查詢用戶。
3. /user/update：更新用戶。
4. /user/delete/{id}：根據 id 刪除用戶。
5. /test/test：測試接口。

下面我們將通過集成 Swagger2，然后為這 5 個 Rest API 自動生成接口文檔。

添加依賴

首先要做的自然是添加 Swagger2 所需要的依賴包：

清單 3. 添加 Swagger 依賴

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

Java 配置

Springfox 提供了一個 Docket 對象，讓我們可以靈活的配置 Swagger 的各項屬性。下面我們新建一個 cn.itweknow.sbswagger.conf.SwaggerConfig.java 類，并增加如下內容:

清單 4. Swagger Java 配置

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
}

注意: @Configuration 是告訴 Spring Boot 需要加載這個配置類，@EnableSwagger2 是啟用 Swagger2，如果沒加的話自然而然也就看不到后面的驗證效果了。

驗證

至此，我們已經成功的在 Spring Boot 項目中集成了 Swagger2，啟動項目后，我們可以通過在瀏覽器中訪問 http://localhost:8080/ v2/api-docs 來驗證，您會發現返回的結果是一段 JSON 串，可讀性非常差。幸運的是 Swagger2 為我們提供了可視化的交互界面 SwaggerUI，下面我們就一起來試試吧。

集成 Swagger UI

添加依賴

和之前一樣，集成的第一步就是添加相關依賴，在 pom.xml 中添加如下內容即可：

清單 5. 添加 Swagger UI 依賴

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

訪問驗證

其實就只需要添加一下依賴就可以了，我們重新啟動一下項目，然后在瀏覽器中訪問 http://localhost:8080/swagger-ui.html 就可以看到如下的效果了:

圖 1. Swagger UI

點擊查看大圖

可以看到雖然可讀性好了一些，但對接口的表述還不是那么的清楚，接下來我們就通過一些高級配置，讓這份文檔變的更加的易讀。

高級配置

文檔相關描述配置

1. 通過在控制器類上增加@Api 注解，可以給控制器增加描述和標簽信息。

清單 6. 給 Controller 添加描述信息

@Api(tags = "用戶相關接口", description = "提供用戶相關的 Rest API")
public class UserController

2. 通過在接口方法上增加 @ApiOperation 注解來展開對接口的描述，當然這個注解還可以指定很多內容，我們在下面的相關注解說明章節中詳細解釋。

清單 7. 給接口添加描述信息

@ApiOperation("新增用戶接口")
@PostMapping("/add")
public boolean addUser(@RequestBody User user) {
    return false;
}

3. 實體描述，我們可以通過 @ApiModel 和 @ApiModelProperty 注解來對我們 API 中所涉及到的對象做描述。

清單 8. 給實體類添加描述信息

@ApiModel("用戶實體")
public class User {
    @ApiModelProperty("用戶 id")
private int id;
}

4. 文檔信息配置，Swagger 還支持設置一些文檔的版本號、聯系人郵箱、網站、版權、開源協議等等信息，但與上面幾條不同的是這些信息不是通過注解配置，而是通過創建一個 ApiInfo 對象，并且使用 Docket.appInfo() 方法來設置，我們在 SwaggerConfig.java 類中新增如下內容即可。

清單 9. 配置文檔信息

@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
            .apis(RequestHandlerSelectors.any())
            .paths(PathSelectors.any())
            .build()
            .apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
return new ApiInfo(
            "Spring Boot 項目集成 Swagger 實例文檔",
            "我的博客網站：https://itweknow.cn，歡迎大家訪問。",
            "API V1.0",
            "Terms of service",
            new Contact("名字想好沒", "https://itweknow.cn", "gancy.programmer@gmail.com"),
                "Apache", "http://www.apache.org/", Collections.emptyList());
}

經過上面的步驟，我們的文檔將會變成下圖的樣子，現在看起來就清楚很多了。

圖 2. 補全信息后的 Swagger 文檔界面

點擊查看大圖

接口過濾

有些時候我們并不是希望所有的 Rest API 都呈現在文檔上，這種情況下 Swagger2 提供給我們了兩種方式配置，一種是基于 @ApiIgnore 注解，另一種是在 Docket 上增加篩選。

1. @ApiIgnore 注解。

如果想在文檔中屏蔽掉刪除用戶的接口（user/delete），那么只需要在刪除用戶的方法上加上 @ApiIgnore 即可。

清單 10. @ApiIgnore 使用實例

@ApiIgnore
public boolean delete(@PathVariable("id") int id)

2. 在 Docket 上增加篩選。Docket 類提供了 apis() 和 paths()兩 個方法來幫助我們在不同級別上過濾接口：

• apis()：這種方式我們可以通過指定包名的方式，讓 Swagger 只去某些包下面掃描。

• paths()：這種方式可以通過篩選 API 的 url 來進行過濾。

在集成 Swagger2 的章節中我們這兩個方法指定的都是掃描所有，沒有指定任何過濾條件。如果我們在我們修改之前定義的 Docket 對象的 apis() 方法和 paths() 方法為下面的內容，那么接口文檔將只會展示 /user/add 和 /user/find/{id} 兩個接口。

清單 11. 使用 Docket 配置接口篩選

.apis(RequestHandlerSelectors.basePackage("cn.itweknow.sbswagger.controller"))
.paths(Predicates.or(PathSelectors.ant("/user/add"),
        PathSelectors.ant("/user/find/*")))

圖 3. 經過篩選過后的 Swagger 文檔界面

點擊查看大圖

自定義響應消息

Swagger 允許我們通過 Docket 的 globalResponseMessage() 方法全局覆蓋 HTTP 方法的響應消息，但是首先我們得通過 Docket 的 useDefaultResponseMessages 方法告訴 Swagger 不使用默認的 HTTP 響應消息，假設我們現在需要覆蓋所有 GET 方法的 500 和 403 錯誤的響應消息，我們只需要在 SwaggerConfig.java 類中的 Docket Bean 下添加如下內容：

清單 12. 自定義響應消息

.useDefaultResponseMessages(false)
.globalResponseMessage(RequestMethod.GET, newArrayList(
new ResponseMessageBuilder()
              .code(500)
              .message("服務器發生異常")
              .responseModel(new ModelRef("Error"))
              .build(),
       new ResponseMessageBuilder()
              .code(403)
              .message("資源不可用")
              .build()
));

添加如上面的代碼后，如下圖所示，您會發現在 SwaggerUI 頁面展示的所有 GET 類型請求的 403 以及 500 錯誤的響應消息都變成了我們自定義的內容。

圖 4. 自定義響應消息

點擊查看大圖

Swagger UI 的使用

接口查看

SwaggerUI 會以列表的方式展示所有掃描到的接口，初始狀態是收縮的，我們只需要點擊展開就好，而且會在左邊標識接口的請求方式（GET、POST、PUT、DELETE 等等）。

圖 5. Swagger 接口列表界面

點擊查看大圖

接口調用

如下圖所示，點擊接口展開后頁面右上角的 Try it out 按鈕后，頁面會變成如圖所示：

圖 6. 接口詳情界面

點擊查看大圖

SwaggerUI 會給我們自動填充請求參數的數據結構，我們需要做的只是點擊 Execute 即可發起調用

圖 7. 接口調用界面

點擊查看大圖

Model

如下圖所示，SwaggerUI 會通過我們在實體上使用的 @ApiModel 注解以及@ApiModelProperty 注解來自動補充實體以及其屬性的描述和備注。

圖 8. 實體界面

點擊查看大圖

相關注解說明

在本章節中我將給出一些 Swagger 中常用的注解以及其常用的屬性，并對其一一解釋，方便您查看。

Controller 相關注解

@Api: 可設置對控制器的描述。

表 1. @Api 主要屬性

接口相關注解

1. @ApiOperation: 可設置對接口的描述。

表 2. @ApiOperation 主要屬性

2. @ApiIgnore: Swagger 文檔不會顯示擁有該注解的接口。

3. @ApiImplicitParams: 用于描述接口的非對象參數集。

4. @ApiImplicitParam: 用于描述接口的非對象參數，一般與 @ApiImplicitParams 組合使用。

表 3. @ApiImplicitParam 主要屬性

Model 相關注解

1. @ApiModel: 可設置接口相關實體的描述。
2. @ApiModelProperty: 可設置實體屬性的相關描述。

表 4. @ApiModelProperty 主要屬性

結束語

在本教程中，我們學會了如何使用 Swagger 2 來生成 Spring Boot REST API 的文檔。我們還研究了如何過濾 API、自定義 HTTP 響應消息以及如何使用 SwaggerUI 直接調用我們的 API。您可以在 Github 上找到本教程的完整實現，這是一個基于 IntelliJ IDEA 的項目，因此它應該很容易導入和運行，當然如果您想對本教程做補充的話歡迎發郵件給我 (mynamecoder@163.com) 或者直接在 GitHub 上提交 Pull Request。

參考資源

Spring 指南
Spring 主頁
Spring Boot 參考指南
Swagger 主頁
本文源碼地址

歡迎關注微信公眾號，獲取更多資源

程序員小明