Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
KES777 opened this issue Aug 13, 2018 · 11 comments
Closed

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

KES777 opened this issue Aug 13, 2018 · 11 comments
Assignees
Labels
clarification requests to clarify, but not change, part of the spec editorial Wording and stylistic issues examples requests for more or better examples in the specification param serialization Issues related to parameter and/or header serialization
Milestone

Comments

@KES777
Copy link

KES777 commented Aug 13, 2018

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
Copy link

silkentrance commented Aug 14, 2018

@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
Copy link
Author

KES777 commented Aug 15, 2018

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
Copy link

silkentrance commented Aug 15, 2018

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
Copy link

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 handrews added examples requests for more or better examples in the specification clarification requests to clarify, but not change, part of the spec param serialization Issues related to parameter and/or header serialization labels Jan 28, 2024
@handrews handrews self-assigned this Apr 28, 2024
@handrews handrews added this to the v3.0.4 milestone Apr 28, 2024
@handrews handrews added the editorial Wording and stylistic issues label May 26, 2024
@handrews
Copy link
Member

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 handrews changed the title Doc improvements: query formats Doc improvements: query formats (n/a usage, "rendering") May 27, 2024
@handrews
Copy link
Member

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

@lornajane
Copy link
Contributor

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
Copy link
Contributor

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
Copy link

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

@handrews
Copy link
Member

handrews commented Jun 8, 2024

@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 handrews removed the review label Jun 9, 2024
@handrews
Copy link
Member

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
clarification requests to clarify, but not change, part of the spec editorial Wording and stylistic issues examples requests for more or better examples in the specification param serialization Issues related to parameter and/or header serialization
Projects
None yet
Development

No branches or pull requests

4 participants