How to Pass Multi Value Query Params in Swagger

how to pass multi value query params in swagger

You are almost there. Name the parameter page_id[], make it type: array and use collectionFormat: multi:

      parameters:
        - name: page_id[]
          in: query
          description: some description
          required: false
          type: array
          items:
            type: string   # or type: integer or whatever the type is 
          collectionFormat: multi

Note that the requests will be sent with the [ and ] characters percent-encoded as %5B and %5D, because they are reserved characters according to RFC 3986.

http://example.com/pages?page_id%5B%5D=123&page_id%5B%5D=456

How does open api 3.0 support a single query param key with multiple values?

You can use something like this...

  - name: param
    in: query
    description: Id description
    required: false
    style: form
    explode: true
    schema:
      type: array
      items:
        type: string

where explode: true will form param=abc¶m=xyz etc
and explode: false will form param=abc,xyz

How to group multiple parameters in Swagger 2.0?

This is not possible with Swagger 2.0, OpenAPI 3.0 or 3.1. I've opened a feature request for this and it is proposed for a future version:

https://github.com/OAI/OpenAPI-Specification/issues/445

Swagger parameters in query and/or body

You'll need to define both query parameters and body parameters but mark all of them as optional. Use the operation description to explain that the client can send the parameters in either query string or body.

swagger: '2.0'
...
paths:
  /foo:
    post:
      consumes:
        - application/json
      parameters:
        - in: query
          name: param1
          type: string
          required: false
        - in: query
          name: param2
          type: string
          required: false
        - in: body
          name: body
          required: false
          schema:
            type: object
            properties:
              param1:
                type: string
              param2:
                type: string

Using OpenAPI 3.0, it's a bit more elegant in that you can reuse the same schema for the query string and the request body:

openapi: 3.0.0
...
paths:
  /foo:
    post:
      parameters:
        # This expands into ?param1=value1¶m2=value2&...
        - in: query
          name: parameters
          required: false
          schema:
            $ref: '#/components/schemas/Parameters'
          style: form
          explode: true
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Parameters'
      responses:
        '200':
          description: OK

components:
  schemas:
    Parameters:
      type: object
      properties:
        param1:
          type: string
        param2:
          type: string

Note for Swagger UI users: Serialization of objects into query string seems to be not supported yet as of UI v. 3.11.0.

How should array query parameters be handled when a single value is expected?

In the OpenAPI definition, if a query parameter allows multiple values, its schema should be defined as array:

  parameters:
    - name: q
      in: query
      schema:
        type: array
        items:
          type: string

When the schema of the parameter is single value, it's considered a violation of the schema for the client to send multiple values. But it is out of the scope of OpenAPI whether the server will tolerate this error.

parameters:
  - name: offset
    in: query
    schema:
      type:  integer
  - name: limit
    in: query
    schema:
      type:  integer

Swagger Editor multiple parameters in body

I'm not sure to understand your question...

• If you are trying to define more than one body parameter for one operation, you can't. As explained in swagger specification:

Body [...] there can only be one body parameter

• If you are trying to send a body with multiple parameters, add an object model in the definitions section and refer it in your body parameter, see below (works with editor.swagger.io):

Your example nodes also are wrong, see here for more details.

swagger: '2.0'
info:
  version: "0.0.1"
  title: Todo App
host: localhost:3000
schemes:
  - http
  - https
consumes:
  - application/json
produces:
  - application/x-www-form-urlencoded
basePath: /
paths:
  # This is a path endpoint. Change it.
  /tasks:
    post:
      description: |
        Add 'Task' object.
      parameters:
        - name: task 
          in: body
          description: task object
          required: true
          schema:
            $ref: '#/definitions/Task'
      responses:
        200:
          description: Successful response
          schema:
              title: Return String
              type: string
              example: "Task added succesfully"
        500:
          description: Error
          schema: 
            type: string
            example: "Could not add Task"
definitions:
  Task:
    description: Task object
    properties:
      name:
        type: string
        description: task object name
      description:
        type: string
        description: task description
    required:
      - name
      - description

---

Related Topics