Springboot集成Swagger2显示字段属性说明
新建spring boot工程
添加依赖
<dependency>
<groupId>io.springfoxgroupId>
<artifactId>springfox-swagger2artifactId>
<version>2.9.2version>
dependency>
<dependency>
<groupId>io.springfoxgroupId>
<artifactId>springfox-swagger-uiartifactId>
<version>2.9.2version>
dependency>
新建swagger配置
import org.springframework.beans.factory.annotation.Value;
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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* @author felix
* @ 日期 2019-05-27 12:03
*/
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
@Value("${swagger.enabled}")
private boolean enable;
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(enable)
.select()
.apis(RequestHandlerSelectors.basePackage("com.fecred.villagedoctor.controller"))
.paths(PathSelectors.any())
.build();
}
@Bean
public Docket healthApi() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("分组名称")
.apiInfo(apiInfo())
.enable(enable)
.select()
//分组的controller层
.apis(RequestHandlerSelectors.basePackage("com.xxx.controller"))
.paths(PathSelectors.regex(".*/health/.*"))
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("标题")
.description("一般描述信息")
.termsOfServiceUrl("http://localhost:8999/")
.contact(new Contact("联系人", "邮箱", "邮箱"))
.version("1.0")
.build();
}
}
新建前后端响应工具类
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
/**
* @author ie
* @ 日期 2019-10-25 14:24
*/
@Data
public class Result<T> {
@ApiModelProperty(value = "状态值")
private int code;
@ApiModelProperty(value = "提示信息")
private String message;
@ApiModelProperty(value = "结果")
private T payload;
private Result<T> code(int code) {
this.code = code;
return this;
}
private Result<T> message(String message) {
this.message = message;
return this;
}
private Result<T> payload(T payload) {
this.payload = payload;
return this;
}
public static <T> Result<T> ok() {
return new Result<T>().code(ResultCode.SUCCESS.getCode()).message(ResultCode.SUCCESS.getMessage()).payload(null);
}
public static <T> Result<T> ok(T payLoad) {
return new Result<T>().code(ResultCode.SUCCESS.getCode()).message(ResultCode.SUCCESS.getMessage()).payload(payLoad);
}
public static <T> Result<T> fail() {
return new Result<T>().code(ResultCode.FAIL.getCode()).message(ResultCode.FAIL.getMessage()).payload(null);
}
public static <T> Result<T> result(int code, String message, T payload) {
return new Result<T>().code(code).message(message).payload(payload);
}
}
状态码
@Getter
public enum ResultCode {
//成功
SUCCESS(20000, "成功"),
//失败
FAIL(40000, "失败"),
//未认证（签名错误）
UNAUTHORIZED(40001, "未认证（签名错误）"),
//接口不存在
NOT_FOUND(40004, "接口不存在"),
//服务器内部错误
INTERNAL_SERVER_ERROR(50000, "服务器内部错误"),
//TOKEN已过期
TOKEN_INVAILD(10001, "TOKEN已过期"),
//TOKEN无效
TOKEN_NOTFOUND(10002, "TOKEN无效");
private final int code;
private final String message;
ResultCode(int code, String message) {
this.code = code;
this.message = message;
}
}
Controller 层使用
@GetMapping(value = "/detail")
@ApiOperation(value = "根据id查询用户")
public Result<User> detail(@RequestParam("userId") Long userId) {
log.info("根据userId查询用户信息【{}】", userId);
User user = userService.findByUserId(userId);
log.info("用户信息【{}】", user.toString());
return Result.ok(user);
}
PageInfo 封装
用于 PageHelper显示属性值
import com.github.pagehelper.Page;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import java.util.Collection;
import java.util.List;
/**
* @author felix
* @ 日期 2019-06-01 15:57
*/
@Data
public class MyPageInfo<T> {
@ApiModelProperty(value = "当前页")
private int pageNum;
@ApiModelProperty(value = "每页的数量")
private int pageSize;
@ApiModelProperty(value = "当前页的数量")
private int size;
/**
* 由于startRow和endRow不常用，这里说个具体的用法
* 可以在页面中"显示startRow到endRow 共size条数据"
*/
@ApiModelProperty(value = "当前页面第一个元素在数据库中的行号")
private int startRow;
@ApiModelProperty(value = "当前页面最后一个元素在数据库中的行号")
private int endRow;
@ApiModelProperty(value = "总页数")
private int pages;
@ApiModelProperty(value = "前一页")
private int prePage;
@ApiModelProperty(value = "下一页")
private int nextPage;
@ApiModelProperty(value = "是否为第一页")
private boolean firstPage = false;
@ApiModelProperty(value = "是否为最后一页")
private boolean lastPage = false;
@ApiModelProperty(value = "是否有前一页")
private boolean hasPreviousPage = false;
@ApiModelProperty(value = "是否有下一页")
private boolean hasNextPage = false;
@ApiModelProperty(value = "导航页码数")
private int navigatePages;
@ApiModelProperty(value = "所有导航页号")
private int[] navigatepageNums;
@ApiModelProperty(value = "导航条上的第一页")
private int navigateFirstPage;
@ApiModelProperty(value = "导航条上的最后一页")
private int navigateLastPage;
@ApiModelProperty(value = "总页数")
private long total;
@ApiModelProperty(value = "结果集")
private List<T> list;
public MyPageInfo() {
this.firstPage = false;
this.lastPage = false;
this.hasPreviousPage = false;
this.hasNextPage = false;
}
public MyPageInfo(List<T> list) {
this(list, 8);
this.list = list;
if (list instanceof Page) {
this.total = ((Page) list).getTotal();
} else {
this.total = (long) list.size();
}
}
public MyPageInfo(List<T> list, int navigatePages) {
this.firstPage = false;
this.lastPage = false;
this.hasPreviousPage = false;
this.hasNextPage = false;
if (list instanceof Page) {
Page page = (Page) list;
this.pageNum = page.getPageNum();
this.pageSize = page.getPageSize();
this.pages = page.getPages();
this.size = page.size();
if (this.size == 0) {
this.startRow = 0;
this.endRow = 0;
} else {
this.startRow = page.getStartRow() + 1;
this.endRow = this.startRow - 1 + this.size;
}
} else if (list instanceof Collection) {
this.pageNum = 1;
this.pageSize = list.size();
this.pages = this.pageSize > 0 ? 1 : 0;
this.size = list.size();
this.startRow = 0;
this.endRow = list.size() > 0 ? list.size() - 1 : 0;
}
if (list instanceof Collection) {
this.navigatePages = navigatePages;
this.calcNavigatepageNums();
this.calcPage();
this.judgePageBoudary();
}
}
private void calcNavigatepageNums() {
//当总页数小于或等于导航页码数时
if (pages <= navigatePages) {
navigatepageNums = new int[pages];
for (int i = 0; i < pages; i++) {
navigatepageNums[i] = i + 1;
}
} else { //当总页数大于导航页码数时
navigatepageNums = new int[navigatePages];
int startNum = pageNum - navigatePages / 2;
int endNum = pageNum + navigatePages / 2;
if (startNum < 1) {
startNum = 1;
//(最前navigatePages页
for (int i = 0; i < navigatePages; i++) {
navigatepageNums[i] = startNum++;
}
} else if (endNum > pages) {
endNum = pages;
//最后navigatePages页
for (int i = navigatePages - 1; i >= 0; i--) {
navigatepageNums[i] = endNum--;
}
} else {
//所有中间页
for (int i = 0; i < navigatePages; i++) {
navigatepageNums[i] = startNum++;
}
}
}
}
private void calcPage() {
if (this.navigatepageNums != null && this.navigatepageNums.length > 0) {
this.navigateFirstPage = this.navigatepageNums[0];
this.navigateLastPage = this.navigatepageNums[this.navigatepageNums.length - 1];
if (this.pageNum > 1) {
this.prePage = this.pageNum - 1;
}
if (this.pageNum < this.pages) {
this.nextPage = this.pageNum + 1;
}
}
}
private void judgePageBoudary() {
this.firstPage = this.pageNum == 1;
this.lastPage = this.pageNum == this.pages || this.pages == 0;
this.hasPreviousPage = this.pageNum > 1;
this.hasNextPage = this.pageNum < this.pages;
}
}
#对pagehelp的使用方式
@GetMapping(value = "/list")
@ApiOperation(value = "获取用户列表")
public ResponseData<MyPageInfo<User>> getList(@RequestParam(value = "page", defaultValue = "1") Integer page, @RequestParam(value = "size", defaultValue = "10") Integer size) {
PageHelper.startPage(page, size);
List<User> list = userService.getList();
log.info("查询用户列表记录数为 ：【{}】", list.size());
MyPageInfo<User> pageInfo = new MyPageInfo<>(list);
return ResultGenerator.successResult(pageInfo);
}
参考
pagehelp文档