pom.xml
<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
创建一个名为 Swagger2Config
的 Java 配置类,代码如下:
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;
/**
* @Classname Swagger2Config
* @Date 2019/3/6 14:08
* @Created by Yuu
*/
@Configuration
public class Swagger2Config {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.yuu.itoken.service.admin.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("iToken 管理员 API 文档")
.description("iToken 管理员 API 网关接口")
.version("1.0.0")
.build();
}
}
启用 Swagger2
Application 中加上注解 @EnableSwagger2
表示开启 Swagger2
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;
/**
* @Classname ServiceAdminApplication
* @Date 2019/2/25 11:16
* @Created by Yuu
*/
@SpringBootApplication(scanBasePackages = "com.yuu.itoken")
@EnableEurekaClient
@EnableSwagger2
@MapperScan(basePackages = {"com.yuu.itoken.common.mapper", "com.yuu.itoken.service.admin.mapper"})
public class ServiceAdminApplication {
public static void main(String[] args) {
SpringApplication.run(ServiceAdminApplication.class, args);
}
}
使用 Swagger2
在 Controller 中增加 Swagger2 相关注解
/**
* 分页查询
*
* @param pageNum
* @param pageSize
* @param tbSysUserJson
* @return
* @throws Exception
*/
@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,
@PathVariable(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 list = pageInfo.getList();
// 封装 Cursor 对象
BaseResult.Cursor cursor = new BaseResult.Cursor();
cursor.setTotal(new Long(pageInfo.getTotal()).intValue());
cursor.setLimit(pageInfo.getPageNum());
cursor.setOffset(pageInfo.getPageSize());
return BaseResult.ok(list, cursor);
}
Swagger 注解说明
@Api
:修饰整个类,描述 Controller 的作用@ApiOperation
:描述一个类的一个方法,或者说一个接口@ApiParam
:单个参数描述@ApiModel
:用对象来接收参数@ApiProperty
:用对象接收参数时,描述对象的一个字段@ApiResponse
:HTTP 响应其中 1 个描述@ApiResponses
:HTTP 响应整体描述@ApiIgnore
:使用该注解忽略这个API@ApiError
:发生错误返回的信息@ApiImplicitParam
:一个请求参数@ApiImplicitParams
:多个请求参数
访问 Swagger2
访问地址: http://ip:port/swagger-ui.html