一、簡介
在當下這個前后端分離的技術趨勢下，前端工程師過度依賴后端工程師的接口和數據，給開發帶來了兩大問題：
- 問題一、后端接口查看難：要怎么調用？參數怎么傳遞？有幾個參數？參數都代表什么含義？
- 問題二、返回數據操作難：數據返回不對或者不夠怎么辦？怎么才能靈活的操作數據？
這是很多公司前后端分離之后帶來的困擾，那怎么來解決這些問題？
問題一的一般解決方案：后端團隊共同維護一個在線文檔，每次改接口再去改對應的文檔，但難免會遺漏，花的大力氣但卻效果平平。
問題二的一般解決方案：自己搭建一個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 {
@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
三、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