springdoc-openapi中@ModelAttribute如何在Swagger展示为参数字段

springdoc-openapi 1.6.x版本默认对未显式标记参数解析规则的POJO类型参数存在类型推断偏差：未识别到@ModelAttribute的绑定语义时，会直接将POJO判定为请求体（body）参数。此时在字段上添加@Schema注解仅会修改请求体模型的字段描述，不会改变参数的展示位置。

按优先级从高到低选择即可：

方案1：给方法参数添加@ParameterObject注解（零侵入、最推荐） #

这是springdoc官方提供的专门标记POJO参数平铺为独立请求参数的注解，无需修改全局配置，直接加在控制器方法的对应参数前即可，注意不要导错包：

// 注意导入springdoc 1.6.x对应路径的注解
import org.springdoc.api.annotations.ParameterObject;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.ModelAttribute;
import org.springframework.http.ResponseEntity;

@GetMapping
public ResponseEntity<String> getApplications(
  @ParameterObject // 仅需添加这一行注解
  @ModelAttribute ApplicationFilter applicationFilter
){
  return null;
}

添加后ApplicationFilter内的所有字段会自动解析为独立的请求参数，你之前在字段上配置的@Parameter(required = true)、@Schema等注解的属性（必填标识、字段描述、示例值）都会正常生效。
补充：如果List<Long> ids参数是通过逗号拼接的形式传参，可在字段上补充@Parameter(explode = io.swagger.v3.oas.annotations.enums.Explode.TRUE)，指定参数按数组格式拆分解析。

方案2：开启全局平铺配置（适合大量使用@ModelAttribute的项目） #

如果项目中有大量@ModelAttribute绑定POJO参数的场景，不需要逐个加注解，直接在配置文件中开启springdoc自带的全局平铺开关即可。
yaml格式配置：

springdoc:
  default-flat-param-object: true

properties格式配置：

springdoc.default-flat-param-object=true

开启后所有标注@ModelAttribute的POJO参数、未显式标记参数来源的JavaBean查询参数，都会自动平铺为独立请求参数，无需修改业务代码。

方案3：自定义操作定制器（兜底适配特殊场景） #

如果上述两个方案因为自定义参数解析器、第三方Swagger增强插件（如低版本knife4j）干扰不生效，可以通过注册全局OperationCustomizer强制修正参数识别逻辑：

import org.springdoc.core.customizers.OperationCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.bind.annotation.ModelAttribute;
import java.util.Arrays;

@Configuration
public class SpringDocConfig {
    @Bean
    public OperationCustomizer modelAttributeParamFixCustomizer() {
        return (operation, handlerMethod) -> {
            // 识别所有@ModelAttribute标注的参数，移除错误生成的请求体配置
            boolean hasModelAttributeParam = Arrays.stream(handlerMethod.getMethodParameters())
                    .anyMatch(param -> param.hasParameterAnnotation(ModelAttribute.class));
            if (hasModelAttributeParam) {
                operation.setRequestBody(null);
            }
            return operation;
        };
    }
}

注意：该方案为兜底逻辑，优先选择前两种官方支持的方案，避免自定义逻辑影响后续版本升级。

• 不要给@ModelAttribute标注的POJO类、方法参数添加任何@RequestBody相关注解，否则会强制将参数识别为请求体
• @Schema注解仅作用于模型属性描述，无法修改参数的绑定位置（请求体/查询参数/路径参数）
• springdoc 1.6.9适配Spring Boot 2.5~2.7版本，不要混用springdoc 2.x版本的注解，否则会出现注解不生效的问题

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