學(xué)習(xí)完整課程請(qǐng)移步 互聯(lián)網(wǎng) Java 全棧工程師
本節(jié)視頻
手寫文檔存在的問(wèn)題
- 文檔需要更新的時(shí)候祥国，需要再次發(fā)送一份給前端，也就是文檔更新交流不及時(shí)儡循。
- 接口返回結(jié)果不明確
- 不能直接在線測(cè)試接口计技，通常需要使用工具恩商，比如：
Postman - 接口文檔太多，不好管理
使用 Swagger 解決問(wèn)題
Swagger 也就是為了解決這個(gè)問(wèn)題，當(dāng)然也不能說(shuō) Swagger 就一定是完美的假消，當(dāng)然也有缺點(diǎn)，最明顯的就是代碼植入性比較強(qiáng)岭接。
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.funtl.itoken.service.admin.controller") 為 Controller 包路徑，不然生成的文檔掃描不到接口
創(chuàng)建一個(gè)名為 Swagger2Config 的 Java 配置類鸣戴，代碼如下：
package com.funtl.itoken.service.admin.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;
@Configuration
public class Swagger2Config {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.funtl.itoken.service.admin.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("iToken API 文檔")
.description("iToken API 網(wǎng)關(guān)接口啃沪，http://www.funtl.com")
.termsOfServiceUrl("http://www.funtl.com")
.version("1.0.0")
.build();
}
}
啟用 Swagger2
Application 中加上注解 @EnableSwagger2 表示開啟 Swagger
package com.funtl.itoken.service.admin;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.netflix.eureka.EnableEurekaClient;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import tk.mybatis.spring.annotation.MapperScan;
@SpringBootApplication(scanBasePackages = "com.funtl.itoken")
@EnableEurekaClient
@EnableSwagger2
@MapperScan(basePackages = {"com.funtl.itoken.common.mapper", "com.funtl.itoken.service.admin.mapper"})
public class ServiceAdminApplication {
public static void main(String[] args) {
SpringApplication.run(ServiceAdminApplication.class, args);
}
}
使用 Swagger2
在 Controller 中增加 Swagger2 相關(guān)注解，代碼如下：
/**
* 分頁(yè)查詢
*
* @param pageNum
* @param pageSize
* @param tbSysUserJson
* @return
*/
@ApiOperation(value = "管理員分頁(yè)查詢")
@ApiImplicitParams({
@ApiImplicitParam(name = "pageNum", value = "頁(yè)碼", required = true, dataType = "int", paramType = "path"),
@ApiImplicitParam(name = "pageSize", value = "筆數(shù)", required = true, dataType = "int", paramType = "path"),
@ApiImplicitParam(name = "tbSysUserJson", value = "管理員對(duì)象 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);
// 分頁(yè)后的結(jié)果集
List<TbSysUser> list = pageInfo.getList();
// 封裝 Cursor 對(duì)象
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 注解說(shuō)明
Swagger 通過(guò)注解表明該接口會(huì)生成文檔窄锅，包括接口名创千、請(qǐng)求方法、參數(shù)、返回信息的等等追驴。
-
@Api：修飾整個(gè)類械哟，描述 Controller 的作用 -
@ApiOperation：描述一個(gè)類的一個(gè)方法，或者說(shuō)一個(gè)接口 -
@ApiParam：?jiǎn)蝹€(gè)參數(shù)描述 -
@ApiModel：用對(duì)象來(lái)接收參數(shù) -
@ApiProperty：用對(duì)象接收參數(shù)時(shí)殿雪，描述對(duì)象的一個(gè)字段 -
@ApiResponse：HTTP 響應(yīng)其中 1 個(gè)描述 -
@ApiResponses：HTTP 響應(yīng)整體描述 -
@ApiIgnore：使用該注解忽略這個(gè)API -
@ApiError：發(fā)生錯(cuò)誤返回的信息 -
@ApiImplicitParam：一個(gè)請(qǐng)求參數(shù) -
@ApiImplicitParams：多個(gè)請(qǐng)求參數(shù)
訪問(wèn) Swagger2
訪問(wèn)地址：http://ip:port/swagger-ui.html
