How to specify path like /pets/{id} but with multiple ids?

Question

I want to create a path which accepts any number of IDs separated with commas. It should accept all the following:

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

The book "building apis you won't hate" gave me this idea. How do I do that in swagger?

Please add more details about what exactly you are trying to achieve. Why do you need more than one id? — cassiomolin, Mar 10 '16 at 14:18
@CássioMazzochiMolin to get info about multiple objects. See edit. — CrabMan, Mar 10 '16 at 14:54
Use a query parameter and just repeat it: `GET /pets/id=4&id=10&id=12&id=124&id=2` — cassiomolin, Mar 10 '16 at 14:57
Related question (but not swagger specific): http://stackoverflow.com/questions/4541338/how-to-construct-a-rest-api-that-takes-an-array-of-ids-for-the-resources. — florisla, Mar 10 '16 at 14:59
That's not neat, but most servers will interpret this as a list of values. — cassiomolin, Mar 10 '16 at 15:05

cassiomolin · Answer 1 · 2016-03-10T15:25:52.660

Swagger 2.0 supports the collectionFormat parameter. From the 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.

An example of use can be seen on the 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"
    }
  ]
}

Will this capture `/pets/123` without any commas as an array with 1 element? — CrabMan, Mar 10 '16 at 15:58

How to specify path like /pets/{id} but with multiple ids?

1 Answers1