如何在Quarkus中为返回Map的API响应正确定义@Schema

你当前的200响应schema错误地将结构定义为单个PojoDto对象，但接口实际返回的是Map<String, PojoDto>类型的键值对集合，需要调整@Schema配置来匹配这一结构。

正确配置方式 #

在200响应的@Schema中，需指定类型为OBJECT（对应JSON对象，即Map的序列化形式），同时通过additionalProperties明确Map值的类型为PojoDto。修改后的200响应配置如下：

@APIResponse(
    responseCode = "200",
    description = "OK",
    content = @Content(mediaType = MediaType.APPLICATION_JSON,
        schema = @Schema(
            type = SchemaType.OBJECT,
            additionalProperties = @Schema(implementation = PojoDto.class)
        )
    )
)

配置说明 #

• type = SchemaType.OBJECT：告诉OpenAPI这是一个JSON对象结构，对应Java中的Map类型。
• additionalProperties = @Schema(implementation = PojoDto.class)：指定JSON对象中所有属性的值类型为PojoDto，匹配Map值的类型。

这样配置后，生成的API文档会准确反映接口返回的键值对结构，和实际返回的Map<String, PojoDto>完全一致。

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