作者：方雷
個(gè)人博客：http://blog.chargingbunk.cn/
微信公眾號(hào)：rayson_666(Rayson開發(fā)分享)
個(gè)人專研技術(shù)方向：
- 微服務(wù)方向：springboot, springCloud, Dubbo
- 分布式/高并發(fā)： 分布式鎖， 消息隊(duì)列RabbitMQ
- 大數(shù)據(jù)處理： Hadoop, spark, HBase等
- python方向： python web開發(fā)
喜歡的朋友們可以關(guān)注我的簡書或微信公眾號(hào)(rayson_666), 一起交流學(xué)習(xí)， 后期會(huì)不斷更新有經(jīng)驗(yàn)的干貨.
一，前言
這兩天有新項(xiàng)目即將開工，目前采用前后端分離的模式開發(fā)，我也是第一次進(jìn)行這樣的模式，但是公司有沒有很有經(jīng)驗(yàn)的大佬指點(diǎn)， 之前就靠自己在網(wǎng)上查閱大量的資料，搭建起了springboot+Dubbo+zookeeper的基本框架， 并采用了Maven的多模塊開發(fā)，也是踩過很多的坑，不過沉淀下來的確是滿滿的經(jīng)驗(yàn)和教訓(xùn)。目前這一套基礎(chǔ)框架也已經(jīng)使用到生產(chǎn)環(huán)境當(dāng)中?，F(xiàn)在的項(xiàng)目也是基于maven的多模塊開發(fā)， 一步一步的搭建起滿足項(xiàng)目需求的腳手架， 方便以后可以更快速的開發(fā)新的項(xiàng)目。
前后端分離， 就是后端只負(fù)責(zé)提供前端的接口，為了減少與前端的溝通成本， 可以更直觀，快速地與前端人員進(jìn)行接口對接， 就少不了接口文檔， 而目前最流行地接口文檔插件就是swagger， 目前使用Swagger2版本。
我這兩天就在負(fù)責(zé)搭建Swagger2， 即便網(wǎng)上有很多這方面的教程， 但是都比較零散， 使得我在搭建過程中， 總是會(huì)出現(xiàn)很多莫名奇妙的問題， 出現(xiàn)這些問題的地方， 也沒有一篇好的總結(jié)。所以我把自己在項(xiàng)目中遇到的情況及解決方案記錄下來， 如果我們遇到同樣的情況， 也方便查閱。
二， 開始
1.引入Swagger依賴
在pom.xml中引入 springfox-swagger2 和 springfox-swagger2-ui
<!-- 構(gòu)建Restful Api文檔 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
2. 創(chuàng)建Swagger2配置類
參考網(wǎng)上的配置，根據(jù)實(shí)際項(xiàng)目修改一下就可以了。
package cn.rayson.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
*
* Swagger2配置類
* @author 方雷(Rayson)
* @微信公眾號(hào): rayson_666(Rayson開發(fā)分享) 、
* 分享springBoot springCloud技術(shù), 以及python,大數(shù)據(jù)學(xué)習(xí)系列
* @個(gè)人博客: http://blog.chargingbunk.cn/
* @簡書: http://www.itdecent.cn/u/5b0de5c8dc56
* 2018年6月9日
*/
@Configuration
@EnableSwagger2
public class Swagger2Config {
//swagger2的配置文件，這里可以配置swagger2的一些基本的內(nèi)容，比如掃描的包等等
@Bean
public Docket defaultApi(){
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("默認(rèn)分組").select()
.apis(RequestHandlerSelectors.basePackage("cn.rayson.controller")).paths(PathSelectors.any()).build();
}
//構(gòu)建 api文檔的詳細(xì)信息函數(shù),注意這里的注解引用的是哪個(gè)
// 預(yù)覽地址:swagger-ui.html
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("利用swagger構(gòu)建測試系統(tǒng)api文檔")
.description("接口訪問地址：http://localhost:8080/, by 方雷")
.termsOfServiceUrl("http://localhost:8080/")
//.contact("方雷")
.version("1.0")
.build();
}
}
如上代碼所示， 通過@Configuration注解， 讓springboot來加載該類的配置。在通過@EnableSwagger2注解來啟用Swagger2。
再通過@Bean注入Docket實(shí)體類， apiInfo()用來創(chuàng)建該api的基本信息，這些信息將會(huì)展現(xiàn)在文檔頁面中。
select() 函數(shù)會(huì)返回一個(gè)ApiSelectorBuilder實(shí)例，用來控制哪些接口暴露到swagger頁面中。 本例采用指定包路徑來定義， Swagger會(huì)掃描該包下的所有Controller定義的api, 并生成文檔展現(xiàn)在swagger頁面中（除了接口被@ApiIgnore指定的會(huì)被忽略）
3. 編寫Controller并進(jìn)行Restful接口文檔測試
在Swagger2配置的包掃描路徑下， 新建一個(gè)Controller
package cn.rayson.controller;
import java.util.HashMap;
import java.util.Map;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.bind.annotation.RestController;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
@Api(value="測試api", tags="測試api")
@RestController
public class RestTestController {
@ApiOperation(value="獲取信息", notes="根據(jù)url的id來獲取信息")
@ApiImplicitParam(name = "id", value = "用戶ID", required = true)
@RequestMapping("/test")
@ResponseBody
public Object index(Integer id){
Map map = new HashMap();
map.put("name", "test");
map.put("age", 13);
return map;
}
}
具體注解什么意思，可以自行百度，我們的目的是能成功訪問到swagger頁面，至于以后再慢慢了解。
4. 運(yùn)行成功后的Swagger效果
5. 最后來看看Swagger2的常用注解
swagger通過注解表明該接口會(huì)生成文檔，包括接口名、請求方法、參數(shù)、返回信息的等等。
@Api：修飾整個(gè)類，描述Controller的作用
@ApiOperation：描述一個(gè)類的一個(gè)方法，或者說一個(gè)接口
@ApiParam：單個(gè)參數(shù)描述
@ApiModel：用對象來接收參數(shù)
@ApiProperty：用對象接收參數(shù)時(shí)，描述對象的一個(gè)字段
@ApiResponse：HTTP響應(yīng)其中1個(gè)描述
@ApiResponses：HTTP響應(yīng)整體描述
@ApiIgnore：使用該注解忽略這個(gè)API
@ApiError ：發(fā)生錯(cuò)誤返回的信息
@ApiImplicitParam：一個(gè)請求參數(shù)
@ApiImplicitParams：多個(gè)請求參數(shù)
三，總結(jié)
以上就是SpringBoot整合Swagger2的整體過程，也是我們百度搜索出現(xiàn)基本上已經(jīng)算是爛大街，隨便一搜就可以找到。我為什么又要寫呢？當(dāng)然是保證整個(gè)知識(shí)的完整性， 為接下來要分享的踩坑并填坑做鋪墊，為以后的項(xiàng)目開發(fā)中少走彎路。
