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

2022-10-10 08:03:27

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

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

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

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

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

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

说明：作者:刘宏缔邮箱: 371125307@qq.com

二，演示项目的相关信息

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/", "371125307@qq.com"))

                .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)

码农公寓