如何在Swagger中用类或HashMap接收不同名查询参数

场景1：将查询参数封装为实体类（Swagger定义+Controller使用） #

Swagger 配置方式 #

要把多个查询参数封装为实体类，需在 Swagger/OpenAPI 定义中先声明实体结构，再通过引用将其作为查询参数集合：

openapi: 3.0.3
info:
  title: Demo API
  version: 1.0.0
components:
  schemas:
    Query:
      type: object
      properties:
        credentials:
          type: string
        age:
          type: integer
        gender:
          type: string
paths:
  /api/v1:
    get:
      summary: 查询接口
      parameters:
        - in: query
          name: queryParams
          schema:
            $ref: '#/components/schemas/Query'
          style: form
          explode: true  # 关键配置：将实体属性拆分为独立的查询参数
      responses:
        '200':
          description: 成功响应

Controller 层使用步骤 #

1. 创建对应实体类（字段名需与查询参数名完全匹配，或通过注解映射）：

public class Query {
    private String credentials; // 对应查询参数credentials
    private Integer age;       // 对应查询参数age
    private String gender;     // 对应查询参数gender

    // 生成getter、setter方法（Spring依赖这些方法绑定参数）
    public String getCredentials() { return credentials; }
    public void setCredentials(String credentials) { this.credentials = credentials; }
    public Integer getAge() { return age; }
    public void setAge(Integer age) { this.age = age; }
    public String getGender() { return gender; }
    public void setGender(String gender) { this.gender = gender; }
}

2. 在 Controller 方法中直接注入该实体类（Spring 自动将查询参数绑定到实体对象）：

@RestController
@RequestMapping("/api")
public class DemoController {
    @GetMapping("/v1")
    public ResponseEntity<String> getQueryData(@ModelAttribute Query query) {
        // 使用实体对象中的参数
        String credentials = query.getCredentials();
        Integer age = query.getAge();
        String gender = query.getGender();
        // 业务逻辑处理...
        return ResponseEntity.ok("参数接收成功");
    }
}

注：若实体字段名与查询参数名不一致，可在字段上添加 @RequestParam("paramName") 注解指定映射关系。

场景2：将查询参数转为 HashMap/MultiValueMap #

若想统一接收所有查询参数为键值对，可直接使用 Map 或 MultiValueMap 类型：

使用 HashMap（适合无重复参数的场景） #

@RestController
@RequestMapping("/api")
public class DemoController {
    @GetMapping("/v1")
    public ResponseEntity<String> getQueryMap(@RequestParam Map<String, String> paramMap) {
        // 直接通过key获取参数值，所有值均为String类型
        String credentials = paramMap.get("credentials");
        Integer age = Integer.parseInt(paramMap.get("age")); // 自行转换类型
        String gender = paramMap.get("gender");
        // 业务逻辑处理...
        return ResponseEntity.ok("参数接收成功");
    }
}

使用 MultiValueMap（适合存在重复参数的场景） #

如果同一参数名可能出现多次（如 /api/v1?color=red&color=blue），MultiValueMap 会保存该参数的所有值：

@RestController
@RequestMapping("/api")
public class DemoController {
    @GetMapping("/v1")
    public ResponseEntity<String> getMultiValueMap(@RequestParam MultiValueMap<String, String> paramMap) {
        // 获取单个参数的所有值
        List<String> colorList = paramMap.get("color");
        // 获取单个参数的第一个值
        String credentials = paramMap.getFirst("credentials");
        // 类型转换示例
        Integer age = Integer.parseInt(paramMap.getFirst("age"));
        // 业务逻辑处理...
        return ResponseEntity.ok("参数接收成功");
    }
}

注：两种方式接收的参数值均为 String 类型，需根据业务需求自行转换为对应的数据类型。

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