如何通过Swagger注解自定义HashMap键的显示示例？

针对你在Swagger 1.5.18中遇到的HashMap<String, CustomObject>属性示例生成不符合需求的问题，这里有几个可行的注解实现方案，完全不需要硬编码CustomObject的完整结构：

方案1：使用@ApiModelProperty的example字段（推荐） #

你可以直接在@ApiModelProperty的example属性中编写包含指定键名的JSON结构，Swagger会自动识别值的类型为CustomObject，并自动填充该模型的生成示例，无需手动编写CustomObject的所有属性。

修改后的代码如下：

@ApiModelProperty(example = "{\"objectName\": {}}")
public HashMap<String, CustomObject> getObjectMap() {
    return objectMap;
}

这个写法的原理是：Swagger解析到值类型为CustomObject时，会将示例中的{}替换为CustomObject的自动生成示例（基于你给CustomObject类添加的@ApiModelProperty配置），最终生成的示例就是你想要的格式，且CustomObject的结构会自动匹配你的模型定义。

方案2：自定义模型包装类（如果方案1不生效） #

如果方案1的自动填充不生效，你可以创建一个简单的包装类来替代HashMap，通过这个类来精准控制示例的键名：

@ApiModel(description = "自定义对象映射")
public class ObjectMapWrapper {
    @ApiModelProperty(value = "自定义对象") // Swagger会自动填充CustomObject的示例结构
    private CustomObject objectName;

    // 对应的getter和setter方法
}

然后修改你的返回属性类型为这个包装类：

@ApiModelProperty
public ObjectMapWrapper getObjectMap() {
    ObjectMapWrapper wrapper = new ObjectMapWrapper();
    wrapper.setObjectName(objectMap.get("objectName"));
    return wrapper;
}

这个方法虽然需要额外创建一个类，但能更稳定地控制Swagger生成的示例结构，且同样不需要硬编码CustomObject的内容。

注意事项 #

• 确保你的CustomObject类已经正确添加了@ApiModel和@ApiModelProperty注解，这样Swagger才能正确生成它的示例结构。
• Swagger 1.5.18对JSON格式的example字符串要求严格，必须是合法的JSON（比如双引号要在Java字符串中用\"转义）。

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