如何通过Swagger Java注解正确标注Map<String, List<Thing>>类型

阿华AIGC实验室

2026-4-2

如何通过Swagger Java注解正确标注Map<String, List>类型

我太懂你这种闹心的感觉了——用Swagger/OpenAPI标注这种嵌套的Map结构时，要么示例是一堆转义后的JSON字符串，完全没法看；要么就丢了内层List的类型信息，文档展示得驴唇不对马嘴。我之前在项目里也踩过一模一样的坑，给你分享两个亲测有效的解决办法：

方法一：用@MapSchema + @ArraySchema精准定义结构

如果你的项目用的是Swagger的专属注解（比如io.swagger.annotations包下的），直接用@MapSchema来专门描述Map的键值结构，搭配@ArraySchema标记值是数组类型，代码示例如下：

@Schema(
    description = "Groups and the things that belong to them.",
    requiredMode = Schema.RequiredMode.REQUIRED
)
@MapSchema(
    keySchema = @Schema(type = "string", description = "分组名称（字符串类型）"),
    valueSchema = @ArraySchema(schema = @Schema(implementation = Thing.class))
)
private Map<String, List<Thing>> groups;

这个写法的好处是逻辑特别清晰：

keySchema明确告诉Swagger，Map的键是字符串类型（对应你的分组名）
valueSchema用@ArraySchema标记值是一个数组，数组里的元素就是你的Thing类实例
这样生成的文档会完整保留Map<String, List<Thing>>的嵌套层级，Redocly渲染时也会展示结构化的示例，再也不会出现JSON字符串的情况

方法二：用OpenAPI 3.x的@Schema直接指定嵌套结构

如果你的项目用的是OpenAPI 3.x的注解（io.swagger.v3.oas.annotations包），可以直接在@Schema里通过additionalProperties定义值的数组结构，代码更简洁：

@Schema(
    description = "Groups and the things that belong to them.",
    requiredMode = Schema.RequiredMode.REQUIRED,
    additionalProperties = @Schema(
        type = "array",
        items = @Schema(implementation = Thing.class)
    )
)
private Map<String, List<Thing>> groups;

这里的核心是additionalProperties = @Schema(type = "array", items = ...)，直接告诉OpenAPI：Map的每个值都是一个数组，数组元素是Thing类型。这样同样能让文档正确识别嵌套结构，生成的示例也是结构化的。