Spring Boot（九）Swagger2自動生成接口文檔和Mock模擬數據

1、簡介

在當下這個先後端分離的技術趨勢下，前端工程師過分依賴後端工程師的接口和數據，給開發帶來了兩大問題：

<!--more-->

• 問題1、後端接口查看難：要怎麼調用？參數怎麼傳遞？有幾個參數？參數都表明什麼含義？
• 問題2、返回數據操做難：數據返回不對或者不夠怎麼辦？怎麼才能靈活的操做數據？

這是不少公司先後端分離以後帶來的困擾，那怎麼來解決這些問題？

問題一的通常解決方案：後端團隊共同維護一個在線文檔，每次改接口再去改對應的文檔，但不免會遺漏，花的大力氣但卻效果平平。

問題二的通常解決方案：本身搭建一個Mock服務器，而後一個接口一個接口手動去錄規則，仍是一個費力的體力活。

那有沒有最優的解決方案，來解決以上兩個問題呢？答案是確定的，那就是將要登場的「Swagger」和「Easy Mock」。

1.1 Swagger介紹

Swagger是全球最流行的接口文檔自動生成和測試的框架，幾乎支持全部的開發語言。

Swagger官網地址：https://swagger.io/

1.2 Easy Mock介紹

Easy Mock是一個可視化，而且能快速生成 模擬數據 的持久化服務。

Easy Mock能一鍵導入Swagger全部接口，省去了手動錄製接口的麻煩，並且可以完美的適配Swagger中的代碼註釋，可謂開發利器。

Easy Mock數據是保存在雲端的，並且能夠建立團隊項目，能夠真正的實現前端脫離後端進行項目開發。

接下來一塊兒來看看怎麼在項目中集成Swagger和Easy Mock吧。

1.3 開發環境

• JDK 8
• Spring Boot 2.0.4
• Swagger 2.9.2
• IDEA 2018.2

2、Swagger集成

本文介紹的Swagger是基於Spring Boot框架的，一塊兒來看具體的實現步驟。

2.1 添加依賴

配置pom.xml，添加以下代碼：

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

其中：

• springfox-swagger2 用於JSON API文檔的生成；
• springfox-swagger-ui 用於文檔界面展現。

更多版本請訪問：

springfox-swagger2：http://mvnrepository.com/artifact/io.springfox/springfox-swagger2

springfox-swagger-ui：http://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui

2.2 註冊Swagger

在源碼的根目錄也就是Appliction.java的同級目錄，建立Java類「SwaggerConfig.java」（命名無所謂），代碼以下：

import org.springframework.boot.autoconfigure.condition.ConditionalOnExpression;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import static springfox.documentation.builders.PathSelectors.regex;

@Configuration
@EnableSwagger2
@ConditionalOnExpression("${swagger.enable:true}")
public class SwaggerConfig  {
    @Bean
    public Docket swaggerSpringMvcPlugin() {
        ApiInfo apiInfo = new ApiInfo(
                "Spring Boot APIs",
                "Spring Boot + Swagger2",
                "1.0.0",
                null,
                "王磊的博客",
                "做者：王磊",
                "http://www.apigo.cn/");
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .select()
                .paths(regex("/api/.*"))
                .build()
                .apiInfo(apiInfo)
                .useDefaultResponseMessages(false);
        return docket;
    }
}

其中「@ConditionalOnExpression」爲Spring的註解，用戶是否實例化本類，用因而否啓用Swagger的判斷（生產環境須要屏蔽Swagger）。

2.3 生產環境禁用Swagger

是否啓用Swagger是在application.properties文件裏配置的，配置以下：

swagger.enable=true

生產環境禁用，設置爲false便可。

2.4 添加文檔註釋

完成以上三個步驟，已經完成了Spring Boot對Swagger的集成，可是文檔不夠友好，好比類、接口的中文說明、參數的說明，是沒有的，須要在代碼中完成。

以下代碼：

@RestController
@RequestMapping("/api/user")
@Api(tags = "用戶控制器")
public class UserController {
    @ApiOperation(value = "打招呼", notes = "測試方法")
    @ApiImplicitParam(name = "name", value = "姓名")
    @RequestMapping(value = "/sayhi", method = RequestMethod.POST)
    public String sayHi(String name) {
        return "Hello," + name;
    }

    @ApiOperation(value = "獲取全部用戶", notes = "查詢分頁數據")
    @RequestMapping(value = "/getall", method = RequestMethod.POST)
    public String getAll() {
        return "全部用戶";
    }
}

寫完代碼運行項目，在瀏覽器輸入：http://localhost:8080/swagger-ui.html 查看添加註釋的效果，以下圖：

其中@Api是用來描述類的，@ApiOperation是用來描述方法的，@ApiImplicitParam是用來描述參數的，更多註解說明請看下文。

示例下載：https://github.com/vipstone/springboot-example/tree/master/springboot-swagger

3、Swagger文檔註解

咱們如今已經對Swagger有了初步的認識，本節重點來看Swagger註解的使用。

Swagger註解的做用是給接口添加註釋的。

3.1 @Api 類註釋

@Api：用來描述類的，屬性以下：

• tags 描述類的用途
• value 對顯示而言沒有任何用途能夠不用設置

代碼示例：

@Api(tags = "文章接口")

3.2 @ApiOperation 方法註釋

@ApiOperation：用來描述方法的，屬性以下：

• value 方法的描述
• notes 方法備註說明

代碼示例：

@ApiOperation(value = "獲取全部文章", notes = "查詢分頁數據")

效果以下圖：

3.3 @ApiImplicitParams 參數註釋

@ApiImplicitParams：描述多參數

@ApiImplicitParam：描述單參數

屬性以下：

• name 參數
• value 參數的描述
• required 是否必傳
• paramType 參數存放位置：header、query、path(resuful接口)、body、form
• dataType 參數類型
• defaultValue 參數默認值

代碼示例：

@ApiImplicitParams({ ​ @ApiImplicitParam(name = "name", value = "姓名", required = true, paramType = "form"), ​ @ApiImplicitParam(name = "age", value = "年齡", required = true, paramType = "form"), })

效果以下圖：

3.4 @ApiModel 實體對象描述

@ApiModel：實體類名描述，屬性以下：

• description 類描述

@ApiModelProperty：字段描述，屬性以下：

• value 字段描述

示例以下：

@ApiModel(description= "返回響應數據")
public class RestMessage implements Serializable{
    @ApiModelProperty(value = "是否成功")
    private boolean success=true;
    @ApiModelProperty(value = "返回對象")
    private Object data;
    @ApiModelProperty(value = "錯誤編號")
    private Integer errCode;
    @ApiModelProperty(value = "錯誤信息")
    private String message;
    /* getter/setter */
}

4、Easy Mock使用

Easy Mock是在線的Mock（模擬）服務器，註冊帳號便可使用，數據存儲雲端，使用簡單不須要在本地進行任何配置，具體操做步驟以下文。

4.1 註冊帳號

瀏覽器輸入：https://easy-mock.com/login 註冊帳號

4.2 配置Easy Mock項目

進入管理頁面以後，點擊演示我的演示項目（默認建立的能夠直接拿來用），以下圖：

進入接口列表，點擊設置=>點擊Swagger Docs API選擇Upload（本地文件上傳），以下圖：

4.3 導出Swagger接口

瀏覽器訪問：http://localhost:8080/v2/api-docs 就看到項目的全部接口JSON格式的，右鍵另存爲文件，以下圖：

繼續4.2的操做，上傳剛剛保存的JSON文件到Easy Mock。

4.4 更新接口

保存完JSON數據以後就返回到項目的設置頁了，這個時候點擊「同步Swagger」就看到全部接口了。以下圖：

到此爲全部的接口已經導入了，能夠點擊接口列表右側的複製按鈕，進行愉快的調用了。

這個時候就能夠徹底脫離後端了，點擊接口詳情，能夠看出Easy Mock完美識別了Swagger註釋也有了，以下圖：

4.5 修改數據

接口的調用沒問題，接下來就是修改操做數據了，點擊右側的相應接口的修改按鈕，以下圖：

進入編輯頁面，你如今編輯的數據就是接口要返回的數據，數據是JSON格式的，而且是在線保存雲端，無須擔憂數據丟失，以下圖：

編輯完直接點擊更新接口便可，注意編輯頁面還有一個預覽按鈕，點入能夠模擬請求，這下連Postman都省了，效果以下：

5、總結

到此爲止全部內容已經演示完了，咱們解決先後端分離帶來接口管理難、數據操做難的問題。自動生成接口文檔、一鍵模擬數據，讓咱們再也不依賴後端，只專一前端的業務，等後端把接口寫完以後，再進行聯合調試就能夠了，這樣咱們就不費吹灰之力搞定了全部難題，而且靈活的配置讓咱們能夠不影響和污染生產環境，生產環境設置禁用Swagger便可，而且有了預覽功能以後咱們甚至連Postman都省了。

參考資料

swagger2 註解說明：http://www.javashuo.com/article/p-xoxiqszl-dn.html