OpenAPI - 如何描述查询参数？

Question

我想弄清楚如何在 OpenAPI 中记录我的两个查询参数。
过滤
我的过滤遵循 JSON:API 的建议，其形式为，例如:

?filter[post]=1,2,3

?filter[post]=1,2,3&filter[author]=5

filter key 是一个关联数组，可以在我的 API 中包含一组资源名称列表。分配给每个过滤器键的值是单个 id 或逗号分隔的 id 列表。
排序
排序也遵循 JSON:API recommendation ，所以是这样的:

?sort=age

?sort=age,-height

sort查询参数被分配一个排序字段或逗号分隔的排序字段列表的值。请注意，前缀 height 的减号字段表示降序。
问题
我如何代表我的 filtering and sorting in OpenAPI ?
例如，我不确定是否可以指定过滤器键是关联数组，或者它接受逗号分隔的 id 列表。排序几乎相同的问题:如何表示以逗号分隔的排序字段列表？

Answer 1

以下方法应该会有所帮助

parameters:
  - in: query
    name: fields
    style: deepObject
    allowReserved: true
    schema:
      type: object
      properties:
        post:
          type: string
        author:
          type: string
  - in: query
    name: sort
    schema:
      type: array
      items:
        type: string
        enum:
          - age
          - height

其中一部分类似于@Helen 分享的问题。它将使您能够使用它，如下图所示

以及相应的 cURL 命令

curl -X GET "https://editor.swagger.io/user?filter[post]=1,2&filter[author]=3,4&sort=age&sort=height" -H  "accept: */*"

您还可以定义 filter参数如下

parameters:
  - in: query
    name: filter
    style: deepObject
    allowReserved: true
    schema:
      type: object
      properties:
        post:
          type: array
          items:
            type: string
        author:
          type: array
          items:
            type: string

这将导致 UI 更加全面，如下所示

然后 cURL 请求如下所示

curl -X GET "https://editor.swagger.io/user?filter[post]=1&filter[post]=2&filter[author]=3&filter[author]=4&sort=age&sort=height" -H  "accept: */*"

你可能不需要 anyOf因为在方法可能返回基类或其任何子类的对象的情况下，它与继承有关。
引用 oneof-anyof-allof-not - OpenAPI Specification有关它的更多信息。