Springdoc无法将无@RequestBody的POJO参数识别为单独查询参数展示在Swagger UI

方案一：全局启用参数平铺（对齐springfox默认行为） #

Springdoc 提供了内置全局配置项，开启后所有未标注@RequestBody的POJO参数都会自动拆解为独立查询参数展示，直接在Spring Boot配置文件中添加对应配置即可：

• 若使用application.properties：
  springdoc.default-flat-param-object=true
• 若使用application.yml：

springdoc:
  default-flat-param-object: true

该配置对Springdoc 1.x、2.x主流版本均生效。开启后所有无@RequestBody注解的POJO参数都会被识别为查询参数组，自动拆分为字段级独立参数，完全匹配springfox的默认处理逻辑。如果某类接口需要保留POJO作为请求体的识别效果，只需在对应参数上单独添加@RequestBody注解即可，Springdoc会优先识别注解标识，不受全局配置影响。

方案二：单接口级参数平铺（适合混合场景） #

如果不需要全局生效，仅需指定部分接口的POJO参数拆分为查询参数，可直接在控制器方法的POJO参数上添加@ParameterObject注解即可：

注：Spring Boot 2 + Springdoc 1.x 版本，注解包路径为 org.springdoc.api.annotations.ParameterObject；Spring Boot 3 + Springdoc 2.x 版本，注解包路径为 org.springdoc.core.annotations.ParameterObject。

修改后的接口示例：

// 按需导入对应版本的@ParameterObject注解
@GetMapping(path="/")
public void sayHello(@ParameterObject Person person) {
    System.out.println(person);
}

该方式无需修改全局配置，仅对标注了@ParameterObject的参数生效，适合项目中同时存在「POJO拆分为查询参数」和「POJO作为请求体」两种需求的混合场景。

注意事项 #

• 请确保Person类为标准POJO，具备对应字段的getter/setter方法，否则Springdoc无法正常解析字段属性，会导致拆分失败。
• 若项目中自定义了Springdoc的参数解析逻辑、OperationCustomizer实现，需要检查是否存在强制将POJO参数标记为请求体的逻辑，避免自定义逻辑覆盖上述配置的生效效果。

验证方式 #

配置完成后重启服务，访问Springdoc UI页面，对应接口的参数会展示为firstName、lastName、age三个独立的查询参数，与springfox的默认展示效果完全一致。

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