Swagger 1.5.16版本中控制Swagger文件默认属性的问题

我在使用swagger-core/swagger-annotations 1.5.16版本时，碰到了个头疼的问题——没法在生成的Swagger文件里正确控制数据模型的默认属性。我写了个POJO用来定义HTTP POST请求的输入JSON对象，代码大概是这样的：

import com.fasterxml.jackson.annotation.JsonProperty;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@Data
@ApiModel(description = "Parameters to use when creating my object")
public class MyPrototype {
    @JsonProperty(value = "name")
    @ApiModelProperty(/* 我尝试在这里配置默认值，但完全没生效 */)
    private String name;
    
    // 其他属性省略...
}

我试了好几种方式想让默认值在Swagger文档里显示出来，但都没成功，想请教下在这个版本里该怎么正确实现？

针对1.5.16版本的解决方案 #

在swagger-core 1.5.x这个版本里，控制数据模型属性的默认值主要靠@ApiModelProperty的两个属性，得搞清楚它们的区别才能用对：

• 用defaultValue设置属性默认值：这个属性就是用来定义属性的默认值的，配置后会在生成的Swagger文件的default字段里体现。注意字符串类型直接写内容就行，不用额外加引号，比如：

@ApiModelProperty(value = "对象名称", defaultValue = "my_default_name")
@JsonProperty(value = "name")
private String name;

• 用example设置示例值：如果defaultValue没达到你想要的效果，或者你只是想给属性加个示例参考，就用example，它会对应Swagger文档里的example字段：

@ApiModelProperty(value = "对象名称", example = "my_sample_name")
@JsonProperty(value = "name")
private String name;

另外，如果还要控制属性是否必填，可以加上required = true：

@ApiModelProperty(value = "对象名称", required = true, defaultValue = "my_default_name")
@JsonProperty(value = "name")
private String name;

几个要注意的点 #

1. 得确保你的Swagger配置类（比如SwaggerConfig）已经正确扫描到了这个POJO所在的包，不然配置了也不会生效。
2. 对于复杂对象的默认值，1.5.x版本支持得不太好，可能得自己写点自定义扩展逻辑。
3. 如果你是在POJO里给属性直接初始化了值（比如private String name = "default";），swagger-core不会自动把这个值同步到Swagger文档里，必须通过@ApiModelProperty显式配置才行。

内容的提问来源于stack exchange，提问作者Marcus Lind