OpenAPI - 如何描述查询参数？

Question

我想弄清楚如何在 OpenAPI 中记录我的两个查询参数。

过滤

我的过滤遵循JSON:API的建议，例如采用以下形式：

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

该filter键是一个关联数组可以包含在我的API资源名称的一组列表。分配给每个过滤器键的值是单个 id 或逗号分隔的 id 列表。

排序

排序也遵循JSON:API 推荐，所以像这样：

• ?sort=age
• ?sort=age,-height

所述sort查询参数被分配一个排序字段或逗号分隔排序字段的列表的值。请注意，height字段前缀的减号表示降序排序。

题

我如何在 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 规范。