一、簡介

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

• 問題一、后端接口查看難：要怎么調用？參數怎么傳遞？有幾個參數？參數都代表什么含義？
• 問題二、返回數據操作難：數據返回不對或者不夠怎么辦？怎么才能靈活的操作數據？

這是很多公司前后端分離之后帶來的困擾，那怎么來解決這些問題？

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

問題二的一般解決方案：自己搭建一個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

二、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 {@Beanpublic 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

三、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 */ }

四、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都省了，效果如下：

五、總結

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

參考資料

swagger2 注解說明：https://blog.csdn.net/xiaojin21cen/article/details/78654652

總結

以上是生活随笔為你收集整理的Spring Boot（九）Swagger2自动生成接口文档和Mock模拟数据的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。