如何指定像/ 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参数.从文档:

如果使用type,array则确定数组的格式.可能的值是:

• csv: 逗号分隔值: foo,bar
• ssv:空格分隔值: foo bar
• tsv:制表符分隔值: foo\tbar
• pipes:管道分隔值: foo|bar
• multi:对应于多个参数实例,而不是单个实例的多个值foo=bar&foo=baz.这仅适用于"query"或"formData"中的参数.

默认值是csv.

可以在文档中看到使用示例:

{
  "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"
    }
  ]
}