文章首發於個人博客站點:https://donlex.cn
相信使用前後端分離的工程師都對接口文檔折磨過。無論是前端調用後端,還是後端調用後端,都期望有一個好的接口文檔。而Swagger,我個人理解就是把相關的信息存儲在它定義的描述文件裏面(yml或json格式),再通過維護這個描述文件可以去更新接口文檔,以及生成各端代碼,它能夠很好地化解前面所說的尷尬。
這樣項目開始時期,只要前端跟後端定義好返回的數據格式,就可以根據接口文檔進行統一的規範,這樣數據規範起來之後,前端就不需要等到後端開發好接口才能知道具體的數據格式,前端使用mockjs模擬數據進行開發,大大節省了時間,同時也減少了不必要的溝通過程。
個人感覺原生的swagger-UI不太友好,所以在網上找到了swagger-bootstrap-ui,這是國人開發的ui包,感覺非常不錯。
快速開始
引入maven包
由於是springfox-swagger的增強UI包,所以基礎功能依然依賴Swagger,springfox-swagger的jar包必須引入
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
然後引入SwaggerBootstrapUi的jar包
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>
當前最新的是1.9.6版本
編寫Swagger2Config配置文件
Swagger2Config
配置文件如下:
@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
public class SwaggerConfiguration {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("接口文檔")
.description("接口文檔")
.build();
}
}
這裏官網有一個對新手不太友好的小坑,那就是Docket中的apis中設置包的掃描路徑,我之前是直接使用官網的配置類,沒有改變包的掃描路徑,導致文檔沒有顯示接口,而改成RequestHandlerSelectors.withClassAnnotation(RestController.class)
之後就可以了,這樣算是使用了軟編碼吧!
訪問地址
swagger-bootstrap-ui默認訪問地址是:http://${host}:${port}/doc.html
swagger2註解
給Controller類添加swagger2註解就生成相應的接口文檔了。
例如:
@Api(value="/test1", tags="測試接口模塊")
@RestController
public class testContro {
@ApiOperation("test")
@GetMapping("/ha")
public String test(){
return "test成功";
}
@ApiOperation("Area刪除")
@GetMapping("/a")
public String ha(){
return "Area刪除成功";
}
}
運行項目之後就可以看到下面的效果:
最後
有了接口文檔之後,當前後端分離開發的時候,只需要丟一個測試環境的文檔地址過去給前端就可以了,直接看着文檔進行參數對接,同時這個接口文檔的調試功能也是非常不錯的,有時候懶得寫單元測試,直接寫一個查詢的方法獲取數據,再調用請求接口進行調試也是非常方便的。