如何描述查询参数？

Question

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

null

filter键是一个关联数组，可以包含API中的资源名称集合列表。分配给每个筛选项的值是单个id或逗号分隔的id列表。

排序

For排序也遵循JSON：API建议，因此如下所示：

null

例如，我不确定是否可以指定过滤器键是一个关联数组，或者它接受逗号分隔的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
  }

要进行文档排序，您可以按照下面的示例进行

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