Swagger UI OpenAPI 3，查询参数显示为 object 而不是值可变字段

Question

以前在 SpringBoot v2.5.7 中，我有这个 Spring REST controller 方法。 它有一个TestCriteria类型的 DTO，作为路径参数。

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

}

TestCriteria class 是这样的。 （ Language是一个枚举，可以采用EN或FR ）。

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

我使用了 Springfox Swagger (springfox-boot-starter v3)，Swagger UI 如下所示：

但后来我不得不将SpringBoot升级到v3，并为Swagger使用Springdoc和OpenAPI v3。现在TestCriteria class看起来像这样：

public class TestCriteria {

    @Schema(type="array")
    @Parameter(allowEmptyValue = true)
    List<Langauge> languages;

}

现在 Swagger UI 不将languages显示为值可选字段，而是显示为 object。

我也比较了生成的 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 视图，用户可以在其中 select 枚举列表中的值，而不是通过 object 表示获取用户的输入？

Answer 1

终于按预期显示了 Swagger UI。

在 controller 方法参数中，我们需要添加@ParameterObject注解：

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

}

这在Springfox 到 Springdoc 迁移文档中有解释：

如果您使用 object 来捕获多个请求查询参数，请使用@ParameterObject注释该方法参数。