springboot干货——（九【二】）swagger中展示嵌套对象注释

分手后的思念是犯贱 2021-09-28 04:08 1804阅读 0赞

# 一.返回参数模板 #

{
      "code": 0,
      "data": {
        "current": 0,
        "pageList": [
          {
            "activityEndTime": "2019-01-30T05:13:34.655Z",
            "activityName": "string",
            "activityStartTime": "2019-01-30T05:13:34.655Z",
            "adOrderNo": "string",
            "barcode": "string",
            "brandName": "string",
            "createTime": "2019-01-30T05:13:34.655Z",
            "dataDate": "string",
            "merchantCode": "string",
            "merchantId": "string",
            "merchantName": "string",
            "orderCreateDate": "string",
            "productName": "string",
            "productNum": 0,
            "refundAmt": 0,
            "refundReason": "string",
            "refundReasonNum": 0,
            "refundTime": "2019-01-30T05:13:34.655Z",
            "styleNo": "string",
            "thirdLevelNum": "string"
          }
        ],
        "pages": 0,
        "size": 0,
        "total": 0
      },
      "message": "string",
      "success": true
    }

整个返回的json嵌套有三层

# 二.返回模型 #

## 1.最外层模型 ##

因为该对象来自jar，未通过swagger进行注释，故在swagger上无任何显示。

import java.io.Serializable;
    
    public class Result<T> implements Serializable {
        private static final long serialVersionUID = -8782333365744933352L;
        private int code;
        private String message;
        private boolean success = true;
        private T data;
    
        private Result() {
        }
    
        private Result(int code, String message) {
            this.code = code;
            this.message = message;
        }
    
        private Result(int code, T data, String message) {
            this.code = code;
            this.message = message;
            this.data = data;
        }
    
        public static <T> Result<T> error() {
            return error(500, "未知异常，请联系管理员");
        }
    
        public static <T> Result<T> error(String message) {
            return error(500, message);
        }
    
        public static <T> Result<T> error(int code, String message) {
            Result result = new Result(code, message);
            result.setSuccess(false);
            return result;
        }
    
        public static <T> Result<T> error(int code, T data, String message) {
            Result result = new Result(code, data, message);
            result.setSuccess(false);
            return result;
        }
    
        public static <T> Result<T> error(CodeMsg msg) {
            return error(msg.getKey(), msg.getMessage());
        }
    
        public static <T> Result<T> success() {
            return success((Object)null, "处理成功");
        }
    
        public static <T> Result<T> success(T data) {
            return success(data, "处理成功");
        }
    
        public static <T> Result<T> success(String message) {
            return success((Object)null, message);
        }
    
        public static <T> Result<T> success(T data, String message) {
            return new Result(0, data, message);
        }
    
        public int getCode() {
            return this.code;
        }
    
        public void setCode(int code) {
            this.code = code;
        }
    
        public String getMessage() {
            return this.message;
        }
    
        public void setMessage(String message) {
            this.message = message;
        }
    
        public boolean isSuccess() {
            return this.success;
        }
    
        public void setSuccess(boolean success) {
            this.success = success;
        }
    
        public T getData() {
            return this.data;
        }
    
        public void setData(T data) {
            this.data = data;
        }
    
        public Result data(T data) {
            return success(data, (String)null);
        }
    }

## 2.次外层模型 ##

import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;
    
    import java.io.Serializable;
    import java.util.List;
    
    /**分页相关DTO
     * Description:
     * 作者：gu.weidong(Marco)
     * date:2019/1/29
     * ProjectName:data-center-parent
     */
    @ApiModel(value = "分页相关DTO")
    public class BasePageReturnDto<T> implements Serializable {
        @ApiModelProperty(value = "总条数")
        int total;
    
        List<T> pageList;
    
        @ApiModelProperty(value = "单页显示数目")
        int size;
    
        @ApiModelProperty(value = "总页数")
        int pages;
    
        @ApiModelProperty(value = "当前页码")
        int current;
    
        public int getTotal() {
            return total;
        }
    
        public void setTotal(int total) {
            this.total = total;
        }
    
        public List<T> getPageList() {
            return pageList;
        }
    
        public void setPageList(List<T> pageList) {
            this.pageList = pageList;
        }
    
        public int getSize() {
            return size;
        }
    
        public void setSize(int size) {
            this.size = size;
        }
    
        public int getPages() {
            return pages;
        }
    
        public void setPages(int pages) {
            this.pages = pages;
        }
    
        public int getCurrent() {
            return current;
        }
    
        public void setCurrent(int current) {
            this.current = current;
        }
    
        public BasePageReturnDto() {
        }
    
        public BasePageReturnDto(int total, int pages, int size, int current,List<T>  pageList) {
            this.total = total;
            this.pageList = pageList;
            this.size = size;
            this.pages = pages;
            this.current = current;
        }
    }

## 3.最内层模型 ##

import io.swagger.annotations.ApiModelProperty;
    
    /**
     * Description:活动基础模型
     * 作者：gu.weidong(Marco)
     * date:2019/1/23
     * ProjectName:data-center-parent
     */
    public class BaseMerchantActivityPO {
        @ApiModelProperty(value = "活动id")
        protected String liveId;
        @ApiModelProperty(value = "活动名称")
        protected String liveName;
        @ApiModelProperty(value = "活动编号")
        protected String liveNo;
        @ApiModelProperty(value = "开始时间")
        protected String beginTime;
        @ApiModelProperty(value = "结束时间")
        protected String endTime;
        @ApiModelProperty(value = "公司id")
        protected String corpId;
        @ApiModelProperty(value = "公司名称")
        protected String corpName;
        @ApiModelProperty(value = "品牌id")
        protected String brandId;
        @ApiModelProperty(value = "品牌名称")
        protected String brandName;
    
        public String getLiveId() {
            return liveId;
        }
    
        public void setLiveId(String liveId) {
            this.liveId = liveId;
        }
    
        public String getLiveName() {
            return liveName;
        }
    
        public void setLiveName(String liveName) {
            this.liveName = liveName;
        }
    
        public String getLiveNo() {
            return liveNo;
        }
    
        public void setLiveNo(String liveNo) {
            this.liveNo = liveNo;
        }
    
        public String getBeginTime() {
            return beginTime;
        }
    
        public void setBeginTime(String beginTime) {
            this.beginTime = beginTime;
        }
    
        public String getEndTime() {
            return endTime;
        }
    
        public void setEndTime(String endTime) {
            this.endTime = endTime;
        }
        public String getCorpId() {
            return corpId;
        }
    
        public void setCorpId(String corpId) {
            this.corpId = corpId;
        }
    
        public String getCorpName() {
            return corpName;
        }
    
        public void setCorpName(String corpName) {
            this.corpName = corpName;
        }
    
        public String getBrandId() {
            return brandId;
        }
    
        public void setBrandId(String brandId) {
            this.brandId = brandId;
        }
    
        public String getBrandName() {
            return brandName;
        }
    
        public void setBrandName(String brandName) {
            this.brandName = brandName;
        }
    }

import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;
    
    /**活动品牌商品销售指标明细模型
     * Description:
     * 作者：gu.weidong(Marco)
     * date:2019/1/23 17:36
     *  * @Param: null
     * @return
     */
    @ApiModel(value = "活动品牌商品销售指标")
    public class LiveBrandPrdIndicDetailD extends BaseMerchantActivityPO {
        @ApiModelProperty(value = "商品id")
        private String productId;
        @ApiModelProperty(value = "商品名称")
        private String productName;
        @ApiModelProperty(value = "款号")
        private String kuanHao;
        @ApiModelProperty(value = "销售金额")
        private Long saleAmt;
        @ApiModelProperty(value = "销售件数(包括取消)")
        private Long saleNum;
        @ApiModelProperty(value = "转发次数")
        private Long forwordNum;
        @ApiModelProperty(value = "可售库存件数")
        private Long allowStock;
        @ApiModelProperty(value = "当前库存件数")
        private Long currentStock;
        @ApiModelProperty(value = "成交销售件数(不包括取消)")
        private Long realSaleNum;
        @ApiModelProperty(value = "成交销售金额(不包括取消)")
        private Long realSaleAmt;
        @ApiModelProperty(value = "售罄率(不包括取消)")
        private Double saleStockPct;
    
        @ApiModelProperty(value = "活动日期")
        private String liveDate;
    
        public String getLiveDate() {
            return liveDate;
        }
    
        public void setLiveDate(String liveDate) {
            this.liveDate = liveDate;
        }
    
        public String getProductId() {
            return productId;
        }
    
        public void setProductId(String productId) {
            this.productId = productId;
        }
    
        public String getProductName() {
            return productName;
        }
    
        public void setProductName(String productName) {
            this.productName = productName;
        }
    
        public String getKuanHao() {
            return kuanHao;
        }
    
        public void setKuanHao(String kuanHao) {
            this.kuanHao = kuanHao;
        }
    
        public Long getSaleAmt() {
            return saleAmt;
        }
    
        public void setSaleAmt(Long saleAmt) {
            this.saleAmt = saleAmt;
        }
    
        public Long getSaleNum() {
            return saleNum;
        }
    
        public void setSaleNum(Long saleNum) {
            this.saleNum = saleNum;
        }
    
        public Long getForwordNum() {
            return forwordNum;
        }
    
        public void setForwordNum(Long forwordNum) {
            this.forwordNum = forwordNum;
        }
    
        public Long getAllowStock() {
            return allowStock;
        }
    
        public void setAllowStock(Long allowStock) {
            this.allowStock = allowStock;
        }
    
        public Long getCurrentStock() {
            return currentStock;
        }
    
        public void setCurrentStock(Long currentStock) {
            this.currentStock = currentStock;
        }
    
        public Long getRealSaleNum() {
            return realSaleNum;
        }
    
        public void setRealSaleNum(Long realSaleNum) {
            this.realSaleNum = realSaleNum;
        }
    
        public Long getRealSaleAmt() {
            return realSaleAmt;
        }
    
        public void setRealSaleAmt(Long realSaleAmt) {
            this.realSaleAmt = realSaleAmt;
        }
    
        public Double getSaleStockPct() {
            return saleStockPct;
        }
    
        public void setSaleStockPct(Double saleStockPct) {
            this.saleStockPct = saleStockPct;
        }
    }

# 三.service层 #

import java.util.List;
    import com.aikucun.data.center.model.DTO.MerchantDto.MerchantByShowdateDto;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.beans.factory.annotation.Value;
    import org.springframework.boot.SpringApplication;
    import org.springframework.stereotype.Service;
    
    
    
    /**
     * Description:
     * 作者：gu.weidong(Marco)
     * date:2019年1月10日
     * ProjectName:data-center-service
     */
    @Service
    public class MerchantServiceImpl implements MerchantService {
       
    
        @Autowired
        private LiveBrandPrdIndicDetailDMapper liveBrandPrdIndicDetailDMapper;
    
      
    
        //单页显示数据条数限制
        @Value("${limit.page.size}")
        int limitPageSize;
    
       
        @Override
        public Result<BasePageReturnDto<LiveBrandPrdIndicDetailD>> getLiveBrandPrdIndicDetailD(LiveBrandByPageDto liveBrandByPageDto) {
            int pageNum = liveBrandByPageDto.getPageNum();
            int pageSize = liveBrandByPageDto.getPageSize();
            if (pageSize > limitPageSize) {
                return Result.error(ErrorCode.DATA_TOO_LONG.getCode(), ErrorCode.DATA_TOO_LONG.getMsg());
            }
            int count = liveBrandPrdIndicDetailDMapper.getLiveBrandPrdIndicDetailDCount(liveBrandByPageDto);
            int pages = (int)Math.ceil(count / (float) pageSize);
            if(pageNum>pages){
                return Result.error(ErrorCode.PAGE_ERROR.getCode(), ErrorCode.PAGE_ERROR.getMsg());
            }
            int start = (pageNum - 1) * pageSize;
            List<LiveBrandPrdIndicDetailD> liveBrandPrdIndicDetailDList = liveBrandPrdIndicDetailDMapper.getLiveBrandPrdIndicDetailD(liveBrandByPageDto, start, pageSize);
            if (liveBrandPrdIndicDetailDList == null || liveBrandPrdIndicDetailDList.size() <= 0) {
                return Result.error(ErrorCode.DATA_IS_NULL.getCode(), ErrorCode.DATA_IS_NULL.getMsg());
            }
            BasePageReturnDto<LiveBrandPrdIndicDetailD> basePageReturnDto = new BasePageReturnDto<LiveBrandPrdIndicDetailD>(count,pages,pageSize,pageNum,liveBrandPrdIndicDetailDList);
            return Result.success(basePageReturnDto);
        }
    }

# 四.controller层 #

import io.swagger.annotations.*;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.web.bind.annotation.RequestBody;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RestController;
    
    import java.util.List;
    
    /**商家相关接口
     *  Description:
     *  作者：gu.weidong(Marco)
     *  date:2019年1月10日
     *  ProjectName:data-center-facade
     */
    @RestController
    @RequestMapping("/merchant")
    @Api("商家相关接口")
    public class MerchantController {
    	@Autowired
    	MerchantService merchantService;
    
    
    	@RequestMapping("/getLiveBrandPrdIndicDetailD")
    	@ApiOperation(value = "商品销售指标",httpMethod="POST",notes="根据活动id、品牌和日期获取商品销售指标明细")
    	public Result<BasePageReturnDto<LiveBrandPrdIndicDetailD>> getLiveBrandPrdIndicDetailD(@RequestBody LiveBrandByPageDto liveBrandByPageDto){
    		Result<BasePageReturnDto<LiveBrandPrdIndicDetailD>> liveBrandPrdIndicDetailD = merchantService.getLiveBrandPrdIndicDetailD(liveBrandByPageDto);
    		return liveBrandPrdIndicDetailD;
    	}
    }

# 五.展示结果 #

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2d3ZDExNTQ5NzgzNTI_size_16_color_FFFFFF_t_70][]

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2d3ZDExNTQ5NzgzNTI_size_16_color_FFFFFF_t_70 1][]

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2d3ZDExNTQ5NzgzNTI_size_16_color_FFFFFF_t_70]: /images/20210923/ccbf122a41524f99b0b884abec9e7985.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2d3ZDExNTQ5NzgzNTI_size_16_color_FFFFFF_t_70 1]: /images/20210923/00bcda8f1d2448078adce33fe4f9f9db.png