api - 如何指定像/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”这本书给了我这个想法。我如何 Swagger 做到这一点？

Answer 1

Swagger 2.0 支持 collectionFormat范围。来自documentation :

Determines the format of the array if type array is used. Possible values are:

• csv: comma separated values: foo,bar
• ssv: space separated values: foo bar
• tsv: tab separated values: foo\tbar
• pipes: pipe separated values: foo|bar
• multi: corresponds to multiple parameter instances instead of multiple values for a single instance foo=bar&foo=baz. This is valid only for parameters in "query" or "formData".

Default value is 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"
    }
  ]
}