Springboot集成Swagger2显示字段属性说明

新建spring boot工程

添加依赖

		 <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </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文档