spring boot:swagger3文档展示分页和分栏的列表数据（swagger 3.0.0 / spring boot 2.3.3）
一，什么情况下需要展示分页和分栏的数据的文档?
分页时，页面上展示的是同一类型的列表的数据，如图:
分栏时,每行都是一个列表，而且展示的数据类型也可能不同
这也是两种常用的数据返回形式
说明：刘宏缔的架构森林是一个专注架构的博客，
网站：https://blog.imgtouch.com
本文: https://blog.imgtouch.com/index.php/2023/05/25/springbootswagger3-wen-dang-zhan-shi-fen-ye-he-fen-lan-de-lie-biao-shu-ju-swagger300springboot233/
对应的源码可以访问这里获取： 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)
