Any of - while selecting the query parameters in Swagger using Open API 3.0.0

[iappa1]

Hi

I have an API , which can accept multiple parameters like,

https://abc.com/findStatus?petid=12334
https://abc.com/findStatus?petname=cuty
https://abc.com/findStatus?petowner=John

I get same response for all the above url's.

How Can I document this in Swagger using OenAPI 3.0.0 ?

Thanks.

[hkosova]

Are these parameters optional? Or does the endpoint require at least 1 (any) parameter?

Are these parameters mutually exclusive? Or can they be used together, e.g. https://abc.com/findStatus?petname=cuty&petowner=John?

[iappa1]

The endpoint requires at least any one of those parameters, but should be documented as a single API.

They cannot be used together.

[hkosova]

EDIT: Replaced style: deepObject with style: form.

So you have mutually exclusive parameters. A possible way is to define them as a single object-type parameter with additional constraints so that only property can be present, and use style: form to serialize this object as ?propName=value.

      parameters:
        - in: query
          name: filter
          required: true
          schema:
            type: object
            properties:
              petid:
                type: integer
                example: 12334
              petname:
                type: string
                example: cuty
              petowner:
                type: string
                example: John
            minProperties: 1
            maxProperties: 1
            additionalProperties: false
          style: form
          explode: true

or maybe

      parameters:
        - in: query
          name: filter
          required: true
          schema:
            type: object
            properties:
              petid:
                type: integer
                example: 12334
              petname:
                type: string
                example: cuty
              petowner:
                type: string
                example: John
            additionalProperties: false
            oneOf:
              - required: [petid]
              - required: [petname]
              - required: [petowner]
          style: form
          explode: true

There's also a proposal to allow query strings in paths, which (if implemented) would make your scenario a bit easier to describe.

[iappa1]

Hi @hkosova ,
Below is the snapshot of my yaml spec. When I click on execute, nothing is happening. It is same, when tried with other alternative you mentioned before. Please help me with this.

Thanks.

[hkosova]

This repository is for the Specification itself. For tooling-related questions, please open an issue in the corresponding tool's repository.

That said, Swagger UI does not seem to support this yet, according to swagger-api/swagger-ui#3558

[silkentrance]

@iappa1 why do you not keep it simple? just have a query parameter that is a string and provide the property name, e.g. petowner etc. along with the user provided value? And your API is also ambiguous regarding petowner and petname. How would the generated code ever be able to figure out what is what?
Or make it a POST and submit a JSON object that contains the relevant data.

[Ymango123]

I designed a API
paths:
/deal:
get:
responses:
'200':
description: 200 OK
'504':
description: 504 Gateway Timeout
parameters:
- name: query
type: string
required: false
in: query
description: query conditions deal
But I can`t receive the parameters in my back-end service. Do you know the reason?