Swagger v3中如何注解描述HashMap<String,String>类型请求参数

Swagger v3（对应SpringBoot3常用的springdoc-openapi实现）默认对HashMap<String, String>类型的@RequestBody只会生成通用的键值对结构描述，无法展示实际需要接收的具体字段，可通过以下两种方案实现自定义配置，按需选择即可。

方案1：无侵入注解配置（无需修改原有参数接收逻辑） #

如果业务代码必须用HashMap<String, String>接参，不需要修改方法参数类型，直接在接口方法上添加Swagger原生注解，手动声明请求体包含的字段、说明、示例即可。
注意区分两个同名的@RequestBody注解：方法参数上保留Spring原生的@org.springframework.web.bind.annotation.RequestBody，方法上添加Swagger提供的@io.swagger.v3.oas.annotations.parameters.RequestBody用来定义文档规则。

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.media.SchemaProperty;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.ResponseStatus;

@PostMapping("/add")
@ResponseStatus(HttpStatus.CREATED)
@Operation(summary = "新增服务记录")
@io.swagger.v3.oas.annotations.parameters.RequestBody(
        description = "请求参数",
        required = true,
        content = @Content(
                mediaType = "application/json",
                schema = @Schema(
                        type = "object",
                        requiredProperties = {"name", "phone"}, // 配置必填字段名
                        properties = {
                                // 逐个声明HashMap中需要接收的字段
                                @SchemaProperty(name = "name", schema = @Schema(type = "string", description = "用户姓名", example = "张三")),
                                @SchemaProperty(name = "phone", schema = @Schema(type = "string", description = "联系电话", example = "13800138000")),
                                @SchemaProperty(name = "content", schema = @Schema(type = "string", description = "服务诉求内容", example = "咨询开户流程"))
                        }
                )
        )
)
public Atendimento create(@org.springframework.web.bind.annotation.RequestBody HashMap<String, String> param) throws Exception {
    return service.create(param);
}

方案2：定义专用DTO类（长期维护成本更低） #

如果接口字段后续可能调整，更推荐定义专用的参数接收类替换原有的HashMap，Swagger会自动扫描类中的字段生成文档，不需要手动维护每个字段的配置，代码可读性也更高。

1. 首先定义参数DTO：

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;

@Data
@Schema(description = "新增服务记录请求参数")
public class AtendimentoCreateParam {
    @Schema(description = "用户姓名", requiredMode = Schema.RequiredMode.REQUIRED, example = "张三")
    private String name;

    @Schema(description = "联系电话", requiredMode = Schema.RequiredMode.REQUIRED, example = "13800138000")
    private String phone;

    @Schema(description = "服务诉求内容", example = "咨询开户流程")
    private String content;
}

2. 修改Controller方法参数类型，如果业务层必须接收HashMap，加一行转换逻辑即可，原有业务代码不需要改动：

@PostMapping("/add")
@ResponseStatus(HttpStatus.CREATED)
public Atendimento create(@RequestBody AtendimentoCreateParam param) throws Exception {
    // 转成业务层需要的HashMap
    HashMap<String, String> paramMap = new HashMap<>();
    paramMap.put("name", param.getName());
    paramMap.put("phone", param.getPhone());
    paramMap.put("content", param.getContent());
    return service.create(paramMap);
}

效果说明 #

两种方案最终在Swagger UI中都会清晰展示所有请求字段的名称、类型、是否必填、说明、示例值，不会再显示模糊的通用Map结构。如果完全不想改动业务逻辑选方案1，追求代码可维护性选方案2。

内容的提问来源于stack exchange，提问作者Rafael da Silva