OpenAPI - 如何描述查询参数？

Question

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

过滤

我的过滤遵循JSON:API 的建议，例如：

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

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

排序

对于排序也遵循JSON:API recommendation，所以是这样的：

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

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

问题

我如何代表我的filtering and sorting in OpenAPI？

例如，我不确定是否可以指定过滤键是关联数组，或者它接受逗号分隔的 id 列表。排序几乎相同的问题：如何表示以逗号分隔的排序字段列表？

Answer 1

这可能有点旧，但我目前正在记录一个 API，其排序、过滤和动态关系包括遵守 JSON API 规范，我刚刚弄清楚如何正确记录过滤查询参数。以下是用 JSON 编写的，但如果您正在编写 YAML，我希望您能够对其进行调整以满足您的需求

{
    "schema": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "id": {
          "description": "Id of the user",
          "type": "string"
        },
        "referrer_id": {
          "description": "The id of the user that referred the user",
          "type": "string"
        },
        "email_verified": {
          "description": "Whether the user has verified their email address",
          "type": "boolean"
        },
        "trashed": {
          "description": "Whether the user has been soft deleted",
          "type": "string",
          "enum": [
            "with",
            "only"
          ]
        }
      }
    },
    "in": "query",
    "name": "filter",
    "description": "Really long description.........",
    "style": "deepObject",
    "explode": true,
    "allowReserved": true
  }

文档排序可以参考here下面的例子

parameters:
  - in: query
    name: ids
    description: One or more IDs
    required: true
    schema:
      type: array
      items:
        type: integer
    style: form
    explode: false
    examples:
      oneId:
        summary: Example of a single ID
        value: [5]   # ?ids=5
      multipleIds:
        summary: Example of multiple IDs
        value: [1, 5, 7]   # ?ids=1,5,7

Answer 2

以下方法应该会有所帮助

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。