swagger参数为list时example的显示问题

场景：当参数为list等集合类型时，example的属性值如下：

@ApiModelProperty(value = "集合", required = true, example = "[x,y,z]")
private List<String> params;

页面显示的结果为：

{
  "params": "[x,y,z]"
}

而不是期待的：

{
  "params": ["x", "y" , "z"]
}

下面对参数为list时example的显示问题进行探究。

package com.morris.swagger.vo;

import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

import java.util.List;

@Data
public class ListReq {

    @ApiModelProperty(dataType = "List", example = "'[''{''value1''}','{''value2''}'']")
    private List<String> aaa01;

    @ApiModelProperty(dataType = "List", allowableValues = "value1, value2", allowEmptyValue = false)
    private List<String> aaa02;

    @ApiModelProperty(dataType = "List", allowableValues = "value1, value2", allowEmptyValue = true)
    private List<String> aaa03;

    @ApiModelProperty(allowableValues = "value1, value2", allowEmptyValue = false)
    private List<String> aaa04;

    @ApiModelProperty(allowableValues = "value1, value2", allowEmptyValue = true)
    private List<String> aaa05;

    @ApiModelProperty(dataType = "List", example = "value1, value2, value2")
    private List<String> aaa06;

    @ApiModelProperty(dataType = "[Ljava.lang.String;", example = "value1, value2, value2")
    private List<String> aaa07;

    @ApiModelProperty(dataType = "[Ljava.lang.String;")
    private List<String> aaa08;

    @ApiModelProperty(dataType = "[Ljava.lang.String;", example = "'[''{''value1''}','{''value2''}'']")
    private List<String> aaa09;

    @ApiModelProperty(dataType = "[Ljava.lang.String;", allowableValues = "value1, value2", allowEmptyValue = false)
    private List<String> aaa10;

    @ApiModelProperty(dataType = "[Ljava.lang.String;", allowableValues = "value1, value2", allowEmptyValue = true)
    private List<String> aaa11;
}

运行后显示的结果如下：

{
  "aaa01": "'[''{''value1''}','{''value2''}'']",
  "aaa02": {},
  "aaa03": {},
  "aaa04": [
    "string"
  ],
  "aaa05": [
    "string"
  ],
  "aaa06": "value1, value2, value2",
  "aaa07": "value1, value2, value2",
  "aaa08": [
    "string"
  ],
  "aaa09": "'[''{''value1''}','{''value2''}'']",
  "aaa10": [
    "string"
  ],
  "aaa11": [
    "string"
  ]
}

结论：ApiModelProperty doesn’t support example for arrays / Lists
。

详见：https://github.com/swagger-api/swagger-core/issues/3863

项目地址

https://gitee.com/morris131/swagger-demo

参考地址

• https://github.com/swagger-api/swagger-ui

• http://springfox.github.io/springfox/docs/current/