一，什么情況下需要展示分頁和分欄的數據的文檔?
分頁時，頁面上展示的是同一類型的列表的數據，如圖:
分欄時,每行都是一個列表，而且展示的數據類型也可能不同
這也是兩種常用的數據返回形式
說明：劉宏締的架構森林是一個專注架構的博客，地址：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)