SpringBoot3升级后Springdoc OpenAPI查询参数枚举选择失效问题

在SpringBoot v2.5.7版本中，使用Springfox Swagger（springfox-boot-starter v3）时，编写了如下REST控制器方法，以TestCriteria作为查询参数DTO：

@GetMapping(path = "/test")
public void test(TestCriteria testCriteria) {

}

TestCriteria类定义如下（Language为仅支持EN、FR的枚举）：

public class TestCriteria {
    @ApiModelProperty(allowEmptyValue = true)
    List<Language> languages;
    
}

此时Swagger UI中languages字段会显示为可选择枚举值的下拉框。

升级至SpringBoot v3并改用Springdoc + OpenAPI v3后，修改TestCriteria类为：

public class TestCriteria {
    @Schema(type="array")
    @Parameter(allowEmptyValue = true)
    List<Language> languages;
}

但Swagger UI不再将languages展示为枚举选择字段，而是以对象形式让用户输入。

新旧生成的OpenAPI定义对比：
旧API文档：

parameters:
  - name: languages
    in: query
    required: false
    type: array
    items:
      type: string
      enum:
        - EN
        - FR
    collectionFormat: multi
    enum:
      - EN
      - FR

新API文档：

parameters:
  - name: testCriteria
    in: query
    required: true
    schema:
      $ref: '#/components/schemas/TestCriteria'

需要恢复之前的Swagger UI展示效果，让用户能从枚举列表中选择值，而非通过对象形式输入。

要让Springdoc将DTO字段展开为独立的查询参数并显示枚举选项，需按以下步骤修改：

1. 在控制器方法的DTO参数上添加@ParameterObject注解
   这个注解会告诉Springdoc将DTO的每个字段转换为单独的查询参数，而非将整个DTO作为一个对象参数处理。修改后的控制器方法：

@GetMapping(path = "/test")
public void test(@ParameterObject TestCriteria testCriteria) {

}

2. 修正TestCriteria类的注解
   移除字段上的@Parameter注解（该注解用于单个参数，不适合DTO字段），保留@Schema并配置正确的枚举展示属性：

public class TestCriteria {
    @Schema(allowEmptyValue = true, enumAsRef = false)
    List<Language> languages;
}

• enumAsRef = false：确保枚举值直接嵌入到OpenAPI文档中，而非引用组件定义，这样Swagger UI会生成下拉选择框。
• 若Language枚举类未显式配置，确保它是public的标准枚举即可：

public enum Language {
    EN, FR
}

3. 验证效果
   修改完成后，生成的OpenAPI定义会和旧版本类似，languages会作为独立的查询参数出现，带有枚举选项，Swagger UI中也会恢复下拉选择的展示形式。

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