OpenAPI -如何描述查询参数？

Question

我试图找出如何在OpenAPI中记录我的两个查询参数。

滤波

我的筛选遵循JSON:API的建议，其形式如下：

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

filter键是一个关联数组，可以在my中包含一组资源名称列表。分配给每个筛选键的值要么是单个id，要么是逗号分隔的id列表。

排序

排序也遵循JSON:API建议，所以如下所示：

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

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

问题

如何表示我的OpenAPI中的过滤和排序

例如，我不确定我是否能够指定过滤器键是一个关联数组，或者它是否接受一个逗号分隔的it列表。排序几乎同样的问题:如何表示逗号分隔的排序字段列表？

Answer 1

这可能有点老了，但我目前正在记录一个API，它的排序、筛选和动态关系包括遵守JSON规范，我刚刚想出了如何正确地记录filter查询参数。下面是用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
  }

要进行文档排序，可以遵循包含这里的示例，该示例也是在下面编写的

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

其中的一部分类似于“海伦”所提出的问题。它将使您能够使用它，如下图所示

​

​

和相应的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，因为它与继承有关。

有关它的更多信息，请参考任何一种所有的非OpenAPI规范。