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

问题

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?

回答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

回答2:

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!

来源：https://stackoverflow.com/questions/40495880/how-to-define-different-query-parameters-for-same-path-in-openapi-swagger

标签

swagger

openapi