Spring Boot 配置 Swagger2 介面文件引擎
阿新 • • 發佈:2018-11-21
手寫文件存在的問題
- 文件需要更新的時候,需要再次傳送一份給前端,也就是文件更新交流不及時。
- 介面返回結果不明確
- 不能直接線上測試介面,通常需要使用工具,比如:
Postman
- 介面文件太多,不好管理
使用 Swagger 解決問題
Swagger 也就是為了解決這個問題,當然也不能說 Swagger 就一定是完美的,當然也有缺點,最明顯的就是程式碼植入性比較強。
Maven
增加 Swagger2 所需依賴,pom.xml
配置如下:
<!-- Swagger2 Begin --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.8.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.8.0</version> </dependency> <!-- Swagger2 End -->
配置 Swagger2
注意:RequestHandlerSelectors.basePackage("com.xx.controller")
為 Controller 包路徑,不然生成的文件掃描不到介面
建立一個名為 Swagger2Config
的 Java 配置類,程式碼如下:
@Configuration public class Swagger2Config { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.admin.controller")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("iToken API 文件") .description("閘道器介面,http://www.wzhu.tk") .termsOfServiceUrl("http://www.wzhu.tk") .version("1.0.0") .build(); } }
啟用 Swagger2
Application 中加上註解 @EnableSwagger2
表示開啟 Swagger
@EnableSwagger2
public class ServiceAdminApplication {
public static void main(String[] args) {
SpringApplication.run(ServiceAdminApplication.class, args);
}
}
使用 Swagger2
在 Controller 中增加 Swagger2 相關注解,程式碼如下:
@ApiOperation(value = "管理員分頁查詢")
@ApiImplicitParams({
@ApiImplicitParam(name = "pageNum", value = "頁碼", required = true, dataType = "int", paramType = "path"),
@ApiImplicitParam(name = "pageSize", value = "筆數", required = true, dataType = "int", paramType = "path"),
@ApiImplicitParam(name = "tbSysUserJson", value = "管理員物件 JSON 字串", required = false, dataTypeClass = String.class, paramType = "json")
})
@RequestMapping(value = "page/{pageNum}/{pageSize}", method = RequestMethod.GET)
public BaseResult page(
@PathVariable(required = true) int pageNum,
@PathVariable(required = true) int pageSize,
@RequestParam(required = false) String tbSysUserJson
) throws Exception {
TbSysUser tbSysUser = null;
if (tbSysUserJson != null) {
tbSysUser = MapperUtils.json2pojo(tbSysUserJson, TbSysUser.class);
}
PageInfo pageInfo = adminService.page(pageNum, pageSize, tbSysUser);
// 分頁後的結果集
List<TbSysUser> list = pageInfo.getList();
// 封裝 Cursor 物件
BaseResult.Cursor cursor = new BaseResult.Cursor();
cursor.setTotal(new Long(pageInfo.getTotal()).intValue());
cursor.setOffset(pageInfo.getPageNum());
cursor.setLimit(pageInfo.getPageSize());
return BaseResult.ok(list, cursor);
}
Swagger 註解說明
Swagger 通過註解表明該介面會生成文件,包括介面名、請求方法、引數、返回資訊的等等。
@Api
:修飾整個類,描述 Controller 的作用@ApiOperation
:描述一個類的一個方法,或者說一個介面@ApiParam
:單個引數描述@ApiModel
:用物件來接收引數@ApiProperty
:用物件接收引數時,描述物件的一個欄位@ApiResponse
:HTTP 響應其中 1 個描述@ApiResponses
:HTTP 響應整體描述@ApiIgnore
:使用該註解忽略這個API@ApiError
:發生錯誤返回的資訊@ApiImplicitParam
:一個請求引數@ApiImplicitParams
:多個請求引數
訪問 Swagger2