Swagger 2.0（2.9.2）集成Spring Boot时@RequestParam Map参数异常

I’ve run into this exact problem before with Swagger 2.9.2 (and even 2.8.0) in Spring Boot—when using @RequestParam Map<String, String> requestParams, the Swagger UI ends up sending a nested structure like {requestParams={code=1}} instead of the expected flat {code=1}. Let’s break down why this happens and how to fix it:

Why It’s Happening #

Swagger 2.x has a quirk in how it renders @RequestParam Map parameters. By default, it treats the Map as a single request parameter that accepts JSON input. So when you enter {"code":1} in the UI, it wraps that JSON under the parameter name requestParams—hence the nested structure. But what we actually want is for Spring to bind all individual query parameters (like ?code=1&name=foo) directly into the Map.

Solutions #

1. Use @ApiImplicitParams to Define Parameters Explicitly

If you know the possible query parameters ahead of time, this is the simplest fix. Manually declare each parameter so Swagger UI renders individual input fields instead of a single JSON box:

@GetMapping("/your-endpoint")
@ApiImplicitParams({
    @ApiImplicitParam(name = "code", value = "Status code", paramType = "query", dataType = "string"),
    @ApiImplicitParam(name = "name", value = "Entity name", paramType = "query", dataType = "string")
    // Add other expected parameters here
})
public ResponseEntity<?> handleRequest(@RequestParam Map<String, String> requestParams) {
    // Your logic here—requestParams will be flat like {code=1, name=foo}
    return ResponseEntity.ok(requestParams);
}

When users fill out these fields in Swagger UI, Spring automatically binds all query parameters to the Map without nesting.

2. Custom Swagger Plugin for Dynamic Map Parameters

If you need to support arbitrary query parameters (no fixed list), create a custom Swagger plugin to adjust how Map parameters are rendered:

@Component
public class MapQueryParameterPlugin implements ParameterBuilderPlugin {

    @Override
    public void apply(ParameterContext context) {
        ResolvedMethodParameter methodParam = context.resolvedMethodParameter();
        // Check if the parameter is a Map annotated with @RequestParam
        if (Map.class.isAssignableFrom(methodParam.getParameterType().getRawClass())
            && methodParam.hasParameterAnnotation(RequestParam.class)) {
            
            context.parameterBuilder()
                .parameterType("query")
                .name("") // Empty name lets Swagger accept any query parameter
                .allowMultiple(true)
                .modelRef(new ModelRef("string"));
        }
    }

    @Override
    public boolean supports(DocumentationType docType) {
        return DocumentationType.SWAGGER_2.equals(docType);
    }
}

This plugin tells Swagger to treat the Map as a collection of query parameters instead of a single JSON parameter. The UI will show a dynamic input where users can add key-value pairs, and Spring will bind them directly to the flat Map.

3. Replace Map with a DTO (Recommended for Fixed Parameters)

If your query parameters are fixed, using a DTO class is cleaner and avoids Swagger compatibility issues entirely:

// DTO class
@Data
public class RequestParams {
    private String code;
    private String name;
    // Add other parameters with getters/setters (Lombok @Data handles this)
}

// Controller endpoint
@GetMapping("/your-endpoint")
public ResponseEntity<?> handleRequest(RequestParams params) {
    // Convert DTO to Map if needed
    Map<String, String> paramMap = new ObjectMapper().convertValue(params, Map.class);
    return ResponseEntity.ok(paramMap);
}

Swagger will automatically generate a clean form for the DTO fields, and you can easily convert the DTO to a Map if your business logic requires it.

Final Notes #

Downgrading to 2.8.0 doesn’t fix this because the issue exists across multiple Swagger 2.x versions. The above solutions address the root cause by adjusting how Swagger renders Map parameters or avoiding the problematic mapping altogether.

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