spring boot:swagger3文档展示分页和分栏的列表数据（swagger 3.0.0 / spring boot 2.3.3）

一，什么情况下需要展示分页和分栏的数据的文档?

分页时，页面上展示的是同一类型的列表的数据，如图:

分栏时,每行都是一个列表，而且展示的数据类型也可能不同

这也是两种常用的数据返回形式

说明：刘宏缔的架构森林是一个专注架构的博客，地址：https://www.cnblogs.com/architectforest

对应的源码可以访问这里获取： https://github.com/liuhongdi/

说明：作者:刘宏缔 邮箱: [e-mail]

二，演示项目的相关信息

1,项目地址

https://github.com/liuhongdi/swagger3pagination

2,项目功能说明：

演示了分页、分栏时数据文档的展示

3,项目结构：如图:

三，配置文件说明：

1,pom.xml

        <!-- swagger3 begin -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

四，java代码说明

1，Swagger3Config.java

@EnableOpenApi
@Configuration
public class Swagger3Config implements WebMvcConfigurer {

    @Bean
    public Docket createRestApi() {
        //返回文档摘要信息
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .apis(RequestHandlerSelectors.withMethodAnnotation(Operation.class))
                .paths(PathSelectors.any())
                .build()
                .globalRequestParameters(getGlobalRequestParameters())
                .globalResponses(HttpMethod.GET, getGlobalResonseMessage())
                .globalResponses(HttpMethod.POST, getGlobalResonseMessage());
    }

    //生成接口信息，包括标题、联系人等
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger3接口文档")
                .description("如有疑问，请联系开发工程师老刘。")
                .contact(new Contact("刘宏缔", "https://www.cnblogs.com/architectforest/", "[e-mail]"))
                .version("1.0")
                .build();
    }

    //生成全局通用参数
    private List<RequestParameter> getGlobalRequestParameters() {
        List<RequestParameter> parameters = new ArrayList<>();
        parameters.add(new RequestParameterBuilder()
                .name("appid")
                .description("平台id")
                .required(true)
                .in(ParameterType.QUERY)
                .query(q -> q.model(m -> m.scalarModel(ScalarType.STRING)))
                .required(false)
                .build());
        parameters.add(new RequestParameterBuilder()
                .name("udid")
                .description("设备的唯一id")
                .required(true)
                .in(ParameterType.QUERY)
                .query(q -> q.model(m -> m.scalarModel(ScalarType.STRING)))
                .required(false)
                .build());
        parameters.add(new RequestParameterBuilder()
                .name("version")
                .description("客户端的版本号")
                .required(true)
                .in(ParameterType.QUERY)
                .query(q -> q.model(m -> m.scalarModel(ScalarType.STRING)))
                .required(false)
                .build());
         return parameters;
    }

    //生成通用响应信息
    private List<Response> getGlobalResonseMessage() {
        List<Response> responseList = new ArrayList<>();
        responseList.add(new ResponseBuilder().code("404").description("找不到资源").build());
         return responseList;
    }
}

swagger的通用配置

2,HomeController.java

@Api(tags = "首页信息管理")
@Controller
@RequestMapping("/home")
public class HomeController {

    @Operation(summary = "首页详情")
    @GetMapping("/home")
    @ResponseBody
    public RestResult<PageResult<RowResult<Goods,Ad>>> home() {
        //整体的返回
        RestResult res = new RestResult();

        //一行用到的list
        List<Goods> rowList = new ArrayList();
        Goods goodsone = new Goods();
        goodsone.setGoodsId(3L);
        goodsone.setGoodsName("电子书");
        goodsone.setSubject("学python,学ai");
        goodsone.setPrice(new BigDecimal(60));
        goodsone.setStock(10);
        rowList.add(goodsone);

        Goods goodstwo = new Goods();
        goodstwo.setGoodsId(4L);
        goodstwo.setGoodsName("蓝牙音箱");
        goodstwo.setSubject("便携式音质优异");
        goodstwo.setPrice(new BigDecimal(1200.00));
        goodstwo.setStock(30);
        rowList.add(goodstwo);

        //一行用到的result
        RowResult oneRow = new RowResult();
        oneRow.setListGoods(rowList);
        oneRow.setRowType("goods");

        //一行用到的list
        List<Ad> rowList2 = new ArrayList();
        Ad adone = new Ad();
        adone.setTitle("保温杯");
        adone.setImgurl("http://a.com/1.jpg");
        rowList2.add(adone);

        Ad adtwo = new Ad();
        adtwo.setTitle("茶具");
        adtwo.setImgurl("http://a.com/2.jpg");
        rowList2.add(adtwo);

        //一行用到的result
        RowResult twoRow = new RowResult();
        twoRow.setListAd(rowList2);
        twoRow.setRowType("ad");

        //一页用到的list
        List<RowResult> pageList = new ArrayList();
        pageList.add(oneRow);
        pageList.add(twoRow);

        //一页用到的result
        PageResult<List<RowResult>> pres= new PageResult();
        pres.setList(pageList);

        //分页的信息
        PaginationResult pares = new PaginationResult();
        pares.setTotal(10);
        pares.setCurrentPage(3);
        pares.setPerPageCount(10);
        pres.setPagination(pares);

        return res.success(pres);
    }
}

显示分栏的分页效果

3,GoodsController.java

@Api(tags = "商品信息管理接口")
@RestController
@RequestMapping("/goods")
public class GoodsController {

    @Operation(summary = "分页商品列表,得到一页上多件商品的信息")
    @GetMapping("/list")
    public RestResult<PageResult<Goods>> list() {
        //整体返回的result
        RestResult res = new RestResult();
        //一页中的list
        List<Goods> resList = new ArrayList();

        Goods goodsone = new Goods();
        goodsone.setGoodsId(3L);
        goodsone.setGoodsName("电子书");
        goodsone.setSubject("学python,学ai");
        goodsone.setPrice(new BigDecimal(60));
        goodsone.setStock(10);
        resList.add(goodsone);

        Goods goodstwo = new Goods();
        goodstwo.setGoodsId(4L);
        goodstwo.setGoodsName("蓝牙音箱");
        goodstwo.setSubject("便携式音质优异");
        goodstwo.setPrice(new BigDecimal(1200.00));
        goodstwo.setStock(30);
        resList.add(goodstwo);

        //一页的result
        PageResult<List<Goods>> pres= new PageResult();
        pres.setList(resList);

       //一页的分页信息
        PaginationResult pares = new PaginationResult();
        pares.setTotal(10);
        pares.setCurrentPage(3);
        pares.setPerPageCount(10);

        pres.setPagination(pares);

        return res.success(pres);
    }

    @Operation(summary = "提交订单")
    @PostMapping("/order")
    @ApiImplicitParams({
            @ApiImplicitParam(name="userid",value="用户id",dataTypeClass = Long.class, paramType = "query",example="12345"),
            @ApiImplicitParam(name="goodsid",value="商品id",dataTypeClass = Integer.class, paramType = "query",example="12345"),
            @ApiImplicitParam(name="mobile",value="手机号",dataTypeClass = String.class, paramType = "query",example="13866668888"),
            @ApiImplicitParam(name="comment",value="发货备注",dataTypeClass = String.class, paramType = "query",example="请在情人节当天送到")
    })
    public RestResult<String> order(@ApiIgnore @RequestParam Map<String,String> params) {
        System.out.println(params);
        RestResult res = new RestResult();
        return res.success("success");
    }
}

分页，页面上是元素的列表

4，RestResult.java

@ApiModel("api通用返回数据")
public class RestResult<T> {

    //uuid,用作唯一标识符，供序列化和反序列化时检测是否一致
    private static final long serialVersionUID = 7498483649536881777L;
    //标识代码，0表示成功，非0表示出错
    @ApiModelProperty("标识代码,0表示成功，非0表示出错")
    private Integer code;

    //提示信息，通常供报错时使用
    @ApiModelProperty("提示信息,供报错时使用")
    private String msg;

    //正常返回时返回的数据
    @ApiModelProperty("返回的数据")
    private T data;

    //constructor
    public RestResult() {
    }

    //constructor
    public RestResult(Integer status, String msg, T data) {
        this.code = status;
        this.msg = msg;
        this.data = data;
    }

    //返回成功数据
    public RestResult success(T data) {
        return new RestResult(ResponseCode.SUCCESS.getCode(), ResponseCode.SUCCESS.getMsg(), data);
    }

    public static RestResult success(Integer code,String msg) {
        return new RestResult(code, msg, null);
    }

    //返回出错数据
    public static RestResult error(ResponseCode code) {
        return new RestResult(code.getCode(), code.getMsg(), null);
    }

    public Integer getCode() {
        return code;
    }
    public void setCode(Integer code) {
        this.code = code;
    }

    public String getMsg() {
        return msg;
    }
    public void setMsg(String msg) {
        this.msg = msg;
    }

    public T getData() {
        return data;
    }
    public void setData(T data) {
        this.data = data;
    }

}

整体返回的result

5,RowResult.java

@ApiModel("每栏的信息")
public class RowResult<T,K> {
    @ApiModelProperty("当前栏的类型")
    private String rowType;

    @ApiModelProperty("当前栏的标题")
    private String rowTitle;

    @ApiModelProperty("内容列表:商品")
    private List<T> listGoods;

    @ApiModelProperty("内容列表:广告")
    private List<K> listAd;

    public String getRowTitle() {
        return this.rowTitle;
    }
    public void setRowTitle(String rowTitle) {
        this.rowTitle = rowTitle;
    }

    public String getRowType() {
        return this.rowType;
    }
    public void setRowType(String rowType) {
        this.rowType = rowType;
    }

    public void setListGoods(List<T> listGoods) {
        this.listGoods = listGoods;
    }
    public List<T> getListGoods() {
        return this.listGoods;
    }

    public void setListAd(List<K> listAd) {
        this.listAd = listAd;
    }
    public List<K> getListAd() {
        return this.listAd;
    }
}

每行的result

6,PaginationResult.java

@ApiModel("分页信息")
public class PaginationResult {

    @ApiModelProperty("总页数")
    private int total;

    @ApiModelProperty("当前第几页")
    private int currentPage;

    @ApiModelProperty("每页的元素的数量")
    private int perPageCount;

    public int getTotal() {
        return this.total;
    }
    public void setTotal(int total) {
        this.total = total;
    }

    public int getCurrentPage() {
        return this.currentPage;
    }
    public void setCurrentPage(int currentPage) {
        this.currentPage = currentPage;
    }

    public int getPerPageCount() {
        return this.perPageCount;
    }
    public void setPerPageCount(int perPageCount) {
        this.perPageCount = perPageCount;
    }
}

分页信息的result

7,PageResult.java

@ApiModel("分页返回数据")
public class PageResult<T> {

    @ApiModelProperty("列表，分页中的数据")
    private List<T> list;

    @ApiModelProperty("页数信息")
    private PaginationResult pagination;

    public PageResult() {
    }

    public void setList(List list) {
        this.list = list;
    }
    public List<T> getList() {
        return this.list;
    }

    public void setPagination(PaginationResult pagination) {
        this.pagination = pagination;
    }
    public PaginationResult getPagination() {
        return this.pagination;
    }
}

分页的result

8,Goods.java,Ad.java,ResponseCode.java

等文件可以访问github.com

五，测试效果

1,访问分页效果:

http://127.0.0.1:8080/goods/list

返回:

查看swagger:

2,查看分栏并分页的效果:访问:

http://127.0.0.1:8080/home/home

返回：

查看swagger:

六，查看spring boot的版本 ：

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::        (v2.3.3.RELEASE)