Doc improvements: query formats (n/a usage, "rendering")

[KES777]

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#parameter-object-examples

Would it be more clear if an example of query url provided?

For an example, how url query should looks for this? How to repeat the parameter?

An optional query parameter of a string value, allowing multiple values by repeating the query parameter:

[silkentrance]

@KES777 well, this depends on the target language and framework for which you generate the code from the OA specification. Or do you want to do that manually?

[KES777]

I understand that as next:

1. the query come to server: ?color=blue&color=black&color=brown
2. The validator checks that color is array and its values are strings:

name: id
in: query
description: ID of the object to fetch
required: false
schema:
  type: array
  items:
    type: string
style: form
explode: true

Also I do not understand why it is called rendering if this is? parsing query:

The following table shows examples of rendering differences for each value.

[silkentrance]

You have to put that into context. Namely the configuration for the parameter, specifying the style and everything. This is what is shown by the table, of how request parameters will be rendered (internally, marshalled that is as a get request parameter), by the system.

And yes, you are right, the documentation is somewhat misleading.

So instead of rendering differences it should read rendering different representations, if I understand it correctly.

[silkentrance]

Also I do not understand why there are these n/aS. It could simply just render the string as is, or make it an empty string. Similarly so for the array.

[handrews]

With simple, the "n/a" for empty doesn't make sense as it's part of RFC6570 that undefined values are just not serialized for simple, so we should indicate that.

I'm inclined to leave the "n/a"s for the other three even though they arguably ought to mimic form, although we'll see if issue #3849 or PR #3818 flush out some information about how they were intended to work. It would be good to make it a bit more clear that "n/a" in these cases mean "these are special-case styles and not always applicable."

[handrews]

@OAI/tsc review request: Am I missing anything with the n/a's?