springboot快速集成swagger

時間 2019-11-30

標籤 springboot 快速集成 swagger 欄目 Spring 简体版

原文原文鏈接

今天技術總監說：小明，咱們本次3.0改造，使用swagger2.0做爲先後端分離的接口規範，它能夠一鍵生成先後端的API,一勞永逸……小明：？？？html

Spring Boot 框架是目前很是流行的微服務框架，咱們不少狀況下使用它來提供 Rest API，而對於 Rest API 來講很重要的一部份內容就是文檔，Swagger 爲咱們提供了一套經過代碼和註解自動生成文檔的方法，這一點對於保證 API 文檔的及時性將有很大的幫助。本文將使用 Swagger 2 規範的 Springfox 實現來了解如何在 Spring Boot 項目中使用 Swagger，主要包含了如何使用 Swagger 自動生成文檔、使用 Swagger 文檔以及 Swagger 相關的一些高級配置和註解。前端

Swagger 簡介

Swagger 是一套基於 OpenAPI 規範構建的開源工具，能夠幫助咱們設計、構建、記錄以及使用 Rest API。Swagger 主要包含了如下三個部分：java

Swagger Editor：基於瀏覽器的編輯器，咱們可使用它編寫咱們 OpenAPI 規範。
Swagger UI：它會將咱們編寫的 OpenAPI 規範呈現爲交互式的 API 文檔，後文我將使用瀏覽器來查看而且操做咱們的 Rest API。
Swagger Codegen：它能夠經過爲 OpenAPI（之前稱爲 Swagger）規範定義的任何 API 生成服務器存根和客戶端 SDK 來簡化構建過程。

爲何要使用 Swagger

當下不少公司都採起先後端分離的開發模式，前端和後端的工做由不一樣的工程師完成。在這種開發模式下，維持一份及時更新且完整的 Rest API 文檔將會極大的提升咱們的工做效率。傳統意義上的文檔都是後端開發人員手動編寫的，相信你們也都知道這種方式很難保證文檔的及時性，這種文檔長此以往也就會失去其參考意義，反而還會加大咱們的溝通成本。而 Swagger 給咱們提供了一個全新的維護 API 文檔的方式，下面咱們就來了解一下它的優勢：git

代碼變，文檔變。只須要少許的註解，Swagger 就能夠根據代碼自動生成 API 文檔，很好的保證了文檔的時效性。
跨語言性，支持 40 多種語言。
Swagger UI 呈現出來的是一份可交互式的 API 文檔，咱們能夠直接在文檔頁面嘗試 API 的調用，省去了準備複雜的調用參數的過程。程序員
還能夠將文檔規範導入相關的工具（例如 SoapUI）, 這些工具將會爲咱們自動地建立自動化測試。github

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

準備 Spring Boot Web 項目

在這一步咱們將準備一個基礎的 Spring Boot 的 Web 項目，而且提供後面所須要的全部 API。spring

建立一個空的 Spring Boot 項目

您能夠經過 Spring Initializr 頁面生成一個空的 Spring Boot 項目，固然也能夠下載 springboot-pom.xml 文件，而後使用 Maven 構建一個 Spring Boot 項目。項目建立完成後，爲了方便後面代碼的編寫您能夠將其導入到您喜歡的 IDE 中，我這裏選擇了 Intelli IDEA 打開。apache

添加依賴

因爲建立的是一個 Web 項目，因此咱們須要依賴 Spring Boot 的 Web 組件，只須要在 pom.xml 增長以下內容便可：後端

清單 1. 添加 Web 依賴

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

編寫接口

首先咱們建立三個包：cn.itweknow.sbswagger.controller、cn.itweknow.sbswagger.testcontroller 以及 cn.itweknow.sbswagger.model。
在 controller 包下新建 UserController.java 類，在 testcontroller 包下新建 TestController.java 類，在 model 包下新建 User.java 類。
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

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

/user/add：新增用戶。
/user/find/{id}：根據 id 查詢用戶。
/user/update：更新用戶。
/user/delete/{id}：根據 id 刪除用戶。
/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

點擊查看大圖

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

高級配置

文檔相關描述配置

經過在控制器類上增長@Api 註解，能夠給控制器增長描述和標籤信息。

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

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

經過在接口方法上增長 @ApiOperation 註解來展開對接口的描述，固然這個註解還能夠指定不少內容，咱們在下面的相關注解說明章節中詳細解釋。

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

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

實體描述，咱們能夠經過 @ApiModel 和 @ApiModelProperty 註解來對咱們 API 中所涉及到的對象作描述。

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

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

文檔信息配置，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 上增長篩選。

@ApiIgnore 註解。

若是想在文檔中屏蔽掉刪除用戶的接口（user/delete），那麼只須要在刪除用戶的方法上加上 @ApiIgnore 便可。

清單 10. @ApiIgnore 使用實例

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

在 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. 實體界面

點擊查看大圖

註解屬性	描述
paramType	查詢參數類型，實際上就是參數放在那裏。取值： path：以地址的形式提交數據，根據 id 查詢用戶的接口就是這種形式傳參。 query：Query string 的方式傳參。 header：以流的形式提交。 form：以 Form 表單的形式提交。
dataType	參數的數據類型。取值： Long String
name	參數名字。
value	參數意義的描述。
required	是否必填。取值： true：必填參數。 false：非必填參數。

結束語

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