如何用springdoc-openapi将对象转为Swagger独立查询参数

springdoc-openapi完全支持将对象的字段拆分为独立查询参数展示在Swagger文档中，核心是使用@ParameterObject注解，具体实现步骤如下：

• 步骤1：引入正确的springdoc依赖
  如果是Spring Boot项目，推荐引入对应Web类型的starter依赖（示例为WebMVC场景）：

  <!-- Maven依赖示例 -->
  <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
      <version>v2.2.0</version> <!-- 版本需匹配Spring Boot版本：Spring Boot 3.x用2.x系列，2.x用1.x系列 -->
  </dependency>
  

• 步骤2：定义查询参数DTO并添加注解
  为DTO的字段添加@Parameter可自定义Swagger描述，后续在接口方法的对象参数上标记@ParameterObject即可触发拆分：

  public class UserQueryParams {
      @Parameter(description = "用户ID")
      private Long id;
      @Parameter(description = "用户名")
      private String username;
      @Parameter(description = "注册起始时间，格式：yyyy-MM-dd HH:mm:ss")
      private LocalDateTime registerStartTime;
  
      // 必须提供getter方法，springdoc通过getter识别字段
      public Long getId() { return id; }
      public void setId(Long id) { this.id = id; }
      public String getUsername() { return username; }
      public void setUsername(String username) { this.username = username; }
      public LocalDateTime getRegisterStartTime() { return registerStartTime; }
      public void setRegisterStartTime(LocalDateTime registerStartTime) { this.registerStartTime = registerStartTime; }
  }
  

• 步骤3：在接口方法中使用该对象参数
  在Controller接口方法中，将DTO作为参数并标记@ParameterObject：

  @RestController
  @RequestMapping("/users")
  public class UserController {
      @GetMapping
      public List<UserVO> getUsers(@ParameterObject UserQueryParams queryParams) {
          // 业务逻辑实现
          return userService.listUsers(queryParams);
      }
  }
  

完成上述配置后，生成的Swagger文档会把id、username、registerStartTime作为独立查询参数展示，效果和直接在方法中定义多个参数完全一致。

补充说明：

• 无需额外配置全局参数解析，springdoc会自动处理@ParameterObject标记的对象
• 若DTO字段未添加@Parameter注解，springdoc会默认以字段名作为参数描述
• 必须保证DTO字段有对应的getter方法，否则springdoc无法识别字段

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