How to define different query parameters for same path in OpenAPI (Swagger)?

Question

I am starting a REST service, using Swagger Codegen. I need to have different responses for different parameters.

Example: <baseURL>/path can use ?filter1= or ?filter2=, and these parameters should produce different response messages.

I want my OpenAPI YAML file to document these two query params separately. Is this possible?

Answer 1

It is not supported in the 2.0 spec, and not in 3.0 either.

Here are the corresponding proposals in the OpenAPI Specification repository:
Accommodate legacy APIs by allowing query parameters in the path
Querystring in Path Specification

Answer 2

In swagger defining location,type explicitly is what defines these variables. You have all the required fields to avoid collision of variables, for a json body you have to reference a declaration or use an example schema as shown below. For my case I have used a schema example rather than a declaration reference

/auth/account/password/reset/{userId}/{resetToken}:
post:
  consumes:
    - application/json
  parameters:
    - in: path
      name: userId
      type: string
      required: true
    - in: path
      type: string
      name: resetToken
      required: true
    - in: header
      name: authorization
      required: true
      type: string
    - in: body
      name: body
      required: true
      schema:
        type: object
        example:
          password: password
          confirmPassword: password
  responses:
    "200":
      description: OK

Answer 3

If you're still looking, I found out a way around this problem. It's a bit of a hack, but it works.

Basically, you can have two definitions to the same path by adding a slash (/) in the URL.

That way, you can set a response for <baseURL>/path with the ?filter1= parameter and set another response for <baseURL>//path with the ?filter2= parameter. It's also important that you give an unique operationId for each of the definitions.

paths:
   /path/you/want:
      get:
         summary: Test 
         operationId: get1
         parameters:
         - name: filter1
         type: string
         in: path
         required: true
      responses:
         200:
            description: Successful response
            schema:
              $ref: '#/definitions/SomeResponse'

   /path/you//want:
     get:
         summary: Another test
         operationId: get2
         parameters:
         - name: filter2
         type: string
         in: path
         required: true
     responses:
       200:
         description: Successful response
         schema:
           $ref: '#/definitions/SomeOtherResponse'

I tried this with a path parameter and it worked just fine!