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的更多信息。

OpenAPI-如何描述查询参数？

2 个答案: