如何指定 /pets/{id} 之类的路径但具有多个 ID？

Question

我想创建一个可以接受任意数量的以逗号分隔的 ID 的路径。它应该接受以下所有内容：

GET /pets/1,2  # returns info about pets with ids 1, 2
GET /pets/4,10,12,124,2  # same, for pets with ids 4, 10, 12, 124, 2

“构建你不会讨厌的 API”这本书给了我这个想法。 我如何大摇大摆地做到这一点？

Answer 1

Swagger 2.0 支持collectionFormat 参数。来自documentation：

如果使用array 类型，则确定数组的格式。可能的值是：

• csv：逗号分隔值：foo,bar
• ssv：空格分隔值：foo bar
• tsv：制表符分隔值：foo\tbar
• pipes：管道分隔值：foo|bar
• multi：对应多个参数实例，而不是单个实例foo=bar&foo=baz的多个值。这仅对“query”或“formData”中的参数有效。

默认值为csv。

使用示例见documentation：

{
  "get": {
    "description": "Returns pets based on ID",
    "summary": "Find pets by ID",
    "operationId": "getPetsById",
    "produces": [
      "application/json",
      "text/html"
    ],
    "responses": { ... }
  },
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "description": "ID of pet to use",
      "required": true,
      "type": "array",
      "items": {
        "type": "string"
      },
      "collectionFormat": "csv"
    }
  ]
}