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?

[lornajane]

I think the n/a entries are correct and should remain unchanged. I vote for closing this issue without further action, unless someone wants to add a small clarification about what n/a means.

[lornajane]

Agreed in the TSC meeting that we can add a clarification to differentiate between "these two things in a row and column really don't go together" and "empty value"

[silkentrance]

n/a's should be noted as [n/a] or just as [unsupported].

[handrews]

@silkentrance I've expanded PR #3859 (which already addressed the "rendering" part of this) with the remaining fixes. I went with n/a in italics to keep from making the table any wider than it already is. I added bullet points above the table explaining that n/a means the behavior is undefined, and that e/s (which replaced some old n/a entries) means "empty string". We'll see how that lands with folks...

[handrews]

PR merged for 3.0.4 and ported to 3.1.1 via PR #3921!
n/a was kept where described in the previous comment. We ended up changing the "empty" comment to "undefined" and explaining how it related to RFC6570, and denoting empty string results as empty in the table.