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?

Related: [Swagger 2.0 - how to make “one or the other” parameter required?](https://stackoverflow.com/q/29708505/113116) — Helen, Dec 14 '17 at 21:52
OpenAPI just seems unnecessarily restrictive. I recommend considering RAML — kervin, Sep 11 '19 at 15:11

score 11 · Accepted Answer · edited Aug 14 '23 at 15:06

11

It is not supported in the 2.0 spec, and not in 3.x 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

edited Aug 14 '23 at 15:06

Helen

87,344
17
243
314

answered Nov 09 '16 at 05:40

fehguy

6,724
25
23

thank you, then I just have to come to peace with it. Just a follow up, is there any way that I can construct a url like `/path?filter1={value}&filter2={value}.....&filterN={value}` for a filter to occur 'n' times. Can I document this on my yaml and construct in swagger code-gen – Anil Pediredla Nov 09 '16 at 19:42

Giuliana · Answer 2 · 2019-04-12T13:50:14.537

6

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!

edited Apr 12 '19 at 13:50

answered Apr 11 '19 at 23:13

Giuliana

99
1
6

Still the same error. `Query strings in paths are not allowed.` It more has to do with presence of the question mark, rather than trying to adding a new path. – skryvets Feb 03 '20 at 15:18
But what do you need the question mark for? As I understand, you cannot declare the parameters as part of the path, so there really shouldn't be any question marks https://stackoverflow.com/a/30252104/11342147 – Giuliana Feb 04 '20 at 16:34
In some situations you have to work with more complex APIs which perform much broader variety of operations in contrast to basic "CRUD" methods. Following this idea you have to supply various payloads/responses based on the query params. One might say - just add another endpoint? However, what if it's still the same resource, just a different flavor of it? Another good example might be the following github comment - https://github.com/OAI/OpenAPI-Specification/issues/270#issuecomment-248712883. – skryvets Feb 07 '20 at 20:17
@skryvets I know this is 2 years after the fact, but Giuliana was saying you have a literal `?` in your path if you're seeing that error. To include query parameters you don't make the path line `/foo?blah=blah`, you just do `/foo`. – Captain Man Apr 08 '22 at 20:55

score 0 · Answer 3 · answered Dec 19 '21 at 09:32

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

score 0 · Answer 4 · answered May 24 '22 at 03:45

0

In Swagger you can add ? to make endpoints different.

i.e. /articles and /articles?:

When using ? in Swagger editor you will see error:

However on your final Swagger page there will be mark VALID

Additional information:

Remember about unique operationId for duplicated entries

answered May 24 '22 at 03:45

pbaranski

22,778
19
100
117

1

OpenAPI [does not allow](https://github.com/OAI/OpenAPI-Specification/issues/2438#issuecomment-760320471) question marks in paths. Swagger UI is probably just less restrictive than other OpenAPI-based tools. – Helen Aug 14 '23 at 15:25

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

4 Answers4

Linked

Related