一、簡介

在當(dāng)下這個(gè)前后端分離的技術(shù)趨勢下，前端工程師過度依賴后端工程師的接口和數(shù)據(jù)，給開發(fā)帶來了兩大問題：

• 問題一、后端接口查看難：要怎么調(diào)用？參數(shù)怎么傳遞？有幾個(gè)參數(shù)？參數(shù)都代表什么含義？
• 問題二、返回?cái)?shù)據(jù)操作難：數(shù)據(jù)返回不對(duì)或者不夠怎么辦？怎么才能靈活的操作數(shù)據(jù)？

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

問題一的一般解決方案：后端團(tuán)隊(duì)共同維護(hù)一個(gè)在線文檔，每次改接口再去改對(duì)應(yīng)的文檔，但難免會(huì)遺漏，花的大力氣但卻效果平平。

問題二的一般解決方案：自己搭建一個(gè)Mock服務(wù)器，然后一個(gè)接口一個(gè)接口手動(dòng)去錄規(guī)則，還是一個(gè)費(fèi)力的體力活。

那有沒有最優(yōu)的解決方案，來解決以上兩個(gè)問題呢？答案是肯定的，那就是將要登場的“Swagger”和“Easy Mock”。

1.1 Swagger介紹

Swagger是全球最流行的接口文檔自動(dòng)生成和測試的框架，幾乎支持所有的開發(fā)語言。

Swagger官網(wǎng)地址：https://swagger.io/

1.2 Easy Mock介紹

Easy Mock是一個(gè)可視化，并且能快速生成 模擬數(shù)據(jù) 的持久化服務(wù)。

Easy Mock能一鍵導(dǎo)入Swagger所有接口，省去了手動(dòng)錄制接口的麻煩，而且能夠完美的適配Swagger中的代碼注釋，可謂開發(fā)利器。

Easy Mock數(shù)據(jù)是保存在云端的，而且可以創(chuàng)建團(tuán)隊(duì)項(xiàng)目，可以真正的實(shí)現(xiàn)前端脫離后端進(jìn)行項(xiàng)目開發(fā)。

接下來一起來看看怎么在項(xiàng)目中集成Swagger和Easy Mock吧。

1.3 開發(fā)環(huán)境

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

二、Swagger集成

本文介紹的Swagger是基于Spring Boot框架的，一起來看具體的實(shí)現(xiàn)步驟。

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 用于文檔界面展示。

更多版本請(qǐng)?jiān)L問：

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的同級(jí)目錄，創(chuàng)建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的注解，用戶是否實(shí)例化本類，用于是否啟用Swagger的判斷（生產(chǎn)環(huán)境需要屏蔽Swagger）。

2.3 生產(chǎn)環(huán)境禁用Swagger

是否啟用Swagger是在application.properties文件里配置的，配置如下：

swagger.enable=true

生產(chǎn)環(huán)境禁用，設(shè)置為false即可。

2.4 添加文檔注釋

完成以上三個(gè)步驟，已經(jīng)完成了Spring Boot對(duì)Swagger的集成，但是文檔不夠友好，比如類、接口的中文說明、參數(shù)的說明，是沒有的，需要在代碼中完成。

如下代碼：

@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 = "查詢分頁數(shù)據(jù)")@RequestMapping(value = "/getall", method = RequestMethod.POST)public String getAll() {return "所有用戶";} }

寫完代碼運(yùn)行項(xiàng)目，在瀏覽器輸入：http://localhost:8080/swagger-ui.html 查看添加注釋的效果，如下圖：

其中@Api是用來描述類的，@ApiOperation是用來描述方法的，@ApiImplicitParam是用來描述參數(shù)的，更多注解說明請(qǐng)看下文。

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

三、Swagger文檔注解

我們現(xiàn)在已經(jīng)對(duì)Swagger有了初步的認(rèn)識(shí)，本節(jié)重點(diǎn)來看Swagger注解的使用。

Swagger注解的作用是給接口添加注釋的。

3.1 @Api 類注釋

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

• tags 描述類的用途
• value 對(duì)顯示而言沒有任何用途可以不用設(shè)置

代碼示例：

@Api(tags = “文章接口”)

3.2 @ApiOperation 方法注釋

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

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

代碼示例：

@ApiOperation(value = “獲取所有文章”, notes = “查詢分頁數(shù)據(jù)”)

效果如下圖：

3.3 @ApiImplicitParams 參數(shù)注釋

@ApiImplicitParams：描述多參數(shù)

@ApiImplicitParam：描述單參數(shù)

屬性如下：

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

代碼示例：

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

效果如下圖：

3.4 @ApiModel 實(shí)體對(duì)象描述

@ApiModel：實(shí)體類名描述，屬性如下：

• description 類描述

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

• value 字段描述

示例如下：

@ApiModel(description= "返回響應(yīng)數(shù)據(jù)") public class RestMessage implements Serializable{@ApiModelProperty(value = "是否成功")private boolean success=true;@ApiModelProperty(value = "返回對(duì)象")private Object data;@ApiModelProperty(value = "錯(cuò)誤編號(hào)")private Integer errCode;@ApiModelProperty(value = "錯(cuò)誤信息")private String message;/* getter/setter */ }

四、Easy Mock使用

Easy Mock是在線的Mock（模擬）服務(wù)器，注冊賬號(hào)即可使用，數(shù)據(jù)存儲(chǔ)云端，使用簡單不需要在本地進(jìn)行任何配置，具體操作步驟如下文。

4.1 注冊賬號(hào)

瀏覽器輸入：https://easy-mock.com/login 注冊賬號(hào)

4.2 配置Easy Mock項(xiàng)目

進(jìn)入管理頁面之后，點(diǎn)擊演示個(gè)人演示項(xiàng)目（默認(rèn)創(chuàng)建的可以直接拿來用），如下圖：

進(jìn)入接口列表，點(diǎn)擊設(shè)置=>點(diǎn)擊Swagger Docs API選擇Upload（本地文件上傳），如下圖：

4.3 導(dǎo)出Swagger接口

瀏覽器訪問：http://localhost:8080/v2/api-docs 就看到項(xiàng)目的所有接口JSON格式的，右鍵另存為文件，如下圖：

繼續(xù)4.2的操作，上傳剛剛保存的JSON文件到Easy Mock。

4.4 更新接口

保存完JSON數(shù)據(jù)之后就返回到項(xiàng)目的設(shè)置頁了，這個(gè)時(shí)候點(diǎn)擊“同步Swagger”就看到所有接口了。如下圖：

到此為所有的接口已經(jīng)導(dǎo)入了，可以點(diǎn)擊接口列表右側(cè)的復(fù)制按鈕，進(jìn)行愉快的調(diào)用了。

這個(gè)時(shí)候就可以完全脫離后端了，點(diǎn)擊接口詳情，可以看出Easy Mock完美識(shí)別了Swagger注釋也有了，如下圖：

4.5 修改數(shù)據(jù)

接口的調(diào)用沒問題，接下來就是修改操作數(shù)據(jù)了，點(diǎn)擊右側(cè)的相應(yīng)接口的修改按鈕，如下圖：

進(jìn)入編輯頁面，你現(xiàn)在編輯的數(shù)據(jù)就是接口要返回的數(shù)據(jù)，數(shù)據(jù)是JSON格式的，并且是在線保存云端，無須擔(dān)心數(shù)據(jù)丟失，如下圖：

編輯完直接點(diǎn)擊更新接口即可，注意編輯頁面還有一個(gè)預(yù)覽按鈕，點(diǎn)入可以模擬請(qǐng)求，這下連Postman都省了，效果如下：

五、總結(jié)

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

參考資料

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

總結(jié)

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

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。