Swagger直接返回MybatisPlus的Page类文档不展开显示问题剖析

原写法

public RestResponse<Page<RefundPageResp>> refuntList(){
}

public class RestResponse<T> {
    private Integer restCode;
    private String restMsg;
    private T restContext;
}

Page是MybatisPlus的分页查询实体com.baomidou.mybatisplus.extension.plugins.pagination.Page
Swagger文档上是这样显示的，不能展开，显然不符合需求。

思路

因为Page是源码不方便修改，我们先抄一个。

public class MyPage<T> {
    private List<T> records = Collections.emptyList();
    /**
     * 总数
     */
    private long total = 0;
    /**
     * 每页显示条数，默认 10
     */
    private long size = 10;
    /**
     * 当前页
     */
    private long current = 1;
    /**
     * <p>
     * SQL 排序 ASC 数组
     * </p>
     */
    private String[] ascs;
    /**
     * <p>
     * SQL 排序 DESC 数组
     * </p>
     */
    private String[] descs;
    /**
     * <p>
     * 自动优化 COUNT SQL
     * </p>
     */
    private boolean optimizeCountSql = true;
    /**
     * <p>
     * 是否进行 count 查询
     * </p>
     */
    private boolean isSearchCount = true;

    public MyPage(List<T> records, long total, long size, long current) {
        this.records = records;
        this.total = total;
        this.size = size;
        this.current = current;
    }

    public List<T> getRecords() {
        return records;
    }

    public void setRecords(List<T> records) {
        this.records = records;
    }

    public long getTotal() {
        return total;
    }

    public void setTotal(long total) {
        this.total = total;
    }

    public long getSize() {
        return size;
    }

    public void setSize(long size) {
        this.size = size;
    }

    public long getCurrent() {
        return current;
    }

    public void setCurrent(long current) {
        this.current = current;
    }

    public String[] getAscs() {
        return ascs;
    }

    public void setAscs(String[] ascs) {
        this.ascs = ascs;
    }

    public String[] getDescs() {
        return descs;
    }

    public void setDescs(String[] descs) {
        this.descs = descs;
    }

    public boolean isOptimizeCountSql() {
        return optimizeCountSql;
    }

    public void setOptimizeCountSql(boolean optimizeCountSql) {
        this.optimizeCountSql = optimizeCountSql;
    }

    public boolean isSearchCount() {
        return isSearchCount;
    }

    public void setSearchCount(boolean searchCount) {
        isSearchCount = searchCount;
    }

    public static <T> MyPage<T> restPage(Page<T> page) {
        return new MyPage<>(page.getRecords(), page.getTotal(), page.getSize(), page.getCurrent());
    }
}

调整后

public RestResponse<MyPage<RefundPageResp>> refuntList(){
}

无任何变化

我们看到isSearchCount字段应该考虑是否是其影响，is开头的属性字段是会影响字段值的存取的，我们可以看到，我自动生成的两个boolean类型的字段

public boolean isOptimizeCountSql() {
    return optimizeCountSql;
}
public void setOptimizeCountSql(boolean optimizeCountSql) {
    this.optimizeCountSql = optimizeCountSql;
}
public boolean isSearchCount() {
    return isSearchCount;
}

public void setSearchCount(boolean searchCount) {
    isSearchCount = searchCount;
}

原因

optimizeCountSql：字段类型为boolean，其get方法是isOptimizeCountSql()
然而
isSearchCount：按照原则其get方法应该为isIsSearchCount()
同理set方法应该为setIsSearchCount()
调整后

public boolean isIsSearchCount() {
    return isSearchCount;
}
public void setIsSearchCount(boolean searchCount) {
    isSearchCount = searchCount;
}

正常展开

最佳实践

Mybatis的查询对象Page其创建目的是为了构建查询SQL，很多字段是不需要传递给前端的，包括其他框架的分页对象也是不需要返回给前端的，我们可以构建一个自己的PageResult。

@Data
public final class PageResult<T> {
    private final Integer pageNum;
    private final Integer pageSize;
    private final Long total;
    private final List<T> list;

    private PageResult(@NotNull Integer pageNum, @NotNull Integer pageSize, @NotNull Long total, @Nullable List<T> list) {
        this.pageNum = pageNum;
        this.pageSize = pageSize;
        this.total = total;
        this.list = list;
    }


    public static <T> PageResult<T> restPage(@NotNull Integer pageNum, @NotNull Integer pageSize, @NotNull Long total, @Nullable List<T> list) {
        return new PageResult<>(pageNum, pageSize, total, Optional.ofNullable(list).orElse(Collections.emptyList()));
    }

    /**
     * 将MyBatis Plus 分页结果转化为通用结果
     *
     */
    public static <T> PageResult<T> restPage(@NotNull Page<T> page) {
        return new PageResult<>(page.getPageNum(), page.getPageSize(), page.getTotal(), page.getResult());
    }

    /**
     * 将MyBatis Plus 分页结果转化为通用结果
     *
     */
    public static <T> PageResult<T> restPage(@NotNull PageInfo<T> page) {
        return new PageResult<>(page.getPageNum(), page.getPageSize(), page.getTotal(), page.getList());
    }

    /**
     * 将Jpa分页结果转化为通用结果
     */
    public static <T> PageResult<T> restPage(@NotNull org.springframework.data.domain.Page<T> page) {
        return new PageResult<>(page.getNumber()+1, page.getSize(), page.getTotalElements(), page.getContent());
    }

}