Swagger UI OpenAPI 3，查询参数显示为对象而不是可更改值的字段

Question

之前在 SpringBoot v2.5.7 中，我有这个 Spring REST 控制器方法。它有一个

TestCriteria

类型的 DTO，作为路径参数。

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

}

而

TestCriteria

班就是这样的。 （

Language

是一个枚举，可以采用

EN

或

FR

）。

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

我使用了 Springfox Swagger (springfox-boot-starter v3)，Swagger UI 看起来像这样：

但后来我不得不将 SpringBoot 升级到 v3，并使用 Springdoc 和 OpenAPI v3 for Swagger。现在

TestCriteria

类看起来像这样：

public class TestCriteria {

    @Schema(type="array")
    @Parameter(allowEmptyValue = true)
    List<Langauge> 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 视图，用户可以在其中从枚举列表中选择一个值，而不是通过对象表示获取用户的输入？

Answer 1

终于按照预期显示了 Swagger UI。

在控制器方法参数中，我们需要添加

@ParameterObject

注解：

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

}

或者，注释参数类：

@ParameterObject
public class TestCriteria {...}

这在 Springfox 到 Springdoc 迁移文档中进行了解释：

如果您使用对象来捕获多个请求查询参数，请使用

@ParameterObject

注释该方法参数。