Swagger接口返回JSON,Map的字段注释比较优雅的实现

问题描述

看很多小伙伴写的接口，既想要Map的灵活扩展性，又苦于生成的接口文档没办法把已知的字段解释清楚；导致接口文档效果打折扣，还得另行约定文档，或者直接嘴上沟通了事；

目前使用Swagger2形成接口文档时，当系统设计的接口返回的类型不是实体对象时，Swagger2无法在接口文档页面中显示返回结果字段说明，比如返回json、map等可以存储key-val形式的类型；均无法在接口文档页面上显示返回的字段备注说明；

所以怎么才能像实体对象一样显示正常的model字段说明是我们这次需要解决的问题；

解决方式

解决方式，就再定义一个文档说明类，这个类的作用只是用来说明可能得示例字段

具体使用方式如下：

第一步, 定义一个文档说明类

package com.scc.lofselectclub.template.swaggerType;

import io.swagger.annotations.ApiModelProperty;

public class Serie {

   @ApiModelProperty(notes = "Serie property", position = 1, allowEmptyValue = true)
   private String serie;

   @ApiModelProperty(notes = "Quantity property", position = 2, allowEmptyValue = true)
   private String qtity;

   @ApiModelProperty(notes = "percentage", position = 3, allowEmptyValue = true)
   String percentage;

   public String getSerie() {
      return serie;
   }

   public void setSerie(String serie) {
      this.serie = serie;
   }

   public String getQtity() {
      return qtity;
   }

   public void setQtity(String qtity) {
      this.qtity = qtity;
   }
   
   public String getPercentage() {
      return percentage;
   }

   public void setPercentage(String percentage) {
      this.percentage = percentage;
   }

}

第二步 在原来使用Map,List的地方增加 dataType ,指向刚才新建的文档说明示范类

@ApiModelProperty(dataType = "com.scc.lofselectclub.template.swaggerType.Serie", notes = "detail by series", position = 3, allowEmptyValue = true)
   List<Map<String, Object>> series;