How to declare parameter values mixing possibilities

[naldino74]

Hi.

I'm having difficulties while trying to express in a Swagger definition a relatively simple concept.

Let's assume we have a parameter for a GET which takes acceptable values from an array.
How could I clarify within my spec that such values can be mixed (that is, more than one value can be used in a single request) or, at the opposite, that only one of them is accepted in a single request?

Is explicitely declaring the serialization method with "style" and "explode" tags enough to let developers understand thate more than one value can be used in a single request?
At the opposite, without putting in my spec these two tags can I assume that it will be clear enough to devs that they must pass one (and only one) of the possible values?

Here it follows an example built upon my spec.

paths: 
  /pets: 
    get: 
      tags: 
        - petstore
      summary: dummy
      description: dummy
      operationId: get_pets
      security: 
        - oauth2_auth: 
            - limited_read:pets
      parameters:
        - name: breed
          in: query
          schema:
            $ref: "#/components/schemas/breeds"
          style: form
          explode: true
          required: false

...

components:
  schemas:
    breeds: 
      type: string
      enum: 
        - Akita Inu
        - Alaskan Malamute
        - Bull Mastiff
        - Chihuahua
        - Golden Retriever

Thank you for any help!

[naldino74]

I think I've found the answer by myself...

The code above implicitely says that one and only one value can be provided for each parameter.

In order to allow multiple values for a single parameter the $ref must be nested within an array:

      parameters:
        - name: breed
          in: query
          schema:
            type: array
            items:
              $ref: "#/components/schemas/breeds"
          style: form
          explode: true
          required: false

It is worth to note that Swagger UI correctly deals with these situation, presenting a dropdown in a case such as the one in my original example (thus allowing to select only a single value), while switching to a multiple-choice listbox when putting the possible values within an array.

Am I correct?

One last thing: if I'm not wrong, this basically means that it makes no sense to put "style" and "explode" keywords without putting also the "array" one, because in this case no serialization can be applied...
Right?

Thank you again!

[MikeRalphson]

I believe your main point is correct (though the definition of the items schema could be inline, as well as using a $ref as you have it). But style can affect the serialisation of all kinds of parameters, additionally explode: true is only applicable to types array and object.

For a full breakdown of the effect of these fields, see here.

Hope this answers your query (if so, feel free to close the issue).

[naldino74]

Hi @MikeRalphson.

Thank you for your help.

I must confess that I'm still a bit confused (perhaps it's my fault....).

In my original example, at te beginning of this thread, I specified style:form and type:string (one of those primitives described here).

But, as far as I understand, without "nesting" everything under type:array (or possibly type:object, as you said above) only one value (string) can be passed into the parameter at a time and thus no serialization can be applied, basically making style:form useless.

If you pass more than one value to the parameter (e.g., by using some sort of separator) this would probably result in having all the values concatenated and then passed as a single one.

Obviously (well... at least I think so...), any kind of primitive can be used as the type of items within the array.

Am I correct?

Thank you again,

Alberto.

[handrews]

style: form with a string, number, boolean, or null just puts the value directly as the parameter value- there is no need to do anything more complicated, which is why explode: true has no effect for those. Does that answer your question? (if you're still paying attention after... checks timestamp... 4.5 years... 🤦 )

[github-actions]

This issue has been labeled with No recent activity because there has been no recent activity. It will be closed if no further activity occurs within 28 days. Please re-open this issue or open a new one after this delay if you need to.