Open API Specification Swagger 中 API 中的对象作为查询字符串参数

Question

我有一个 API 接受查询参数作为对象。我正在使用它来添加多个过滤器来过滤结果。

当我从 swagger 发出请求时，控制器中的过滤器对象为空。

userFilter 是 POJO class。它用作 query param 并且在控制器中，它作为空值出现。

大摇大摆，如下图

userFilter 尝试从 userFilter 访问任何字段时，未构建对象并在控制器 class 中出现 NullPointerException。

Answer 1

我从 swagger.io 得到了解决方案。

根据解释，content用在complex serialization scenarios中，没有被样式覆盖和爆炸。例如，如果我们需要在 query string 中发送一个 JSON 字符串，如下所示：

filter={"type":"t-shirt","color":"blue"}

在这种情况下，我们需要将 parameter 架构包装到 content/<media-type> 中，如下所示。

我们需要将 content = {@Content(schema = @Schema(type = "object"))} 添加到 @Parameter。

@Parameter(description = "Filters", required = true, content = {@Content(schema = @Schema(type = "object"))})

在 JSON 格式中，它将如下所示。

parameters:
  - in: query
    name: filter
    
    # Wrap 'schema' into 'content.<media-type>'
    content:
      application/json:  # <---- media type indicates how to serialize / deserialize the parameter content
        schema:
          type: object
          properties:
            type:
              type: string
            color:
              type: string

Open API Specification Swagger 中 API 中的对象作为查询字符串参数

Object as query string param in API on Open API Specification Swagger

query-parameters

swagger

swagger-ui

openapi