-
Notifications
You must be signed in to change notification settings - Fork 9.1k
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
"body parameter" example in 3.x does not fit how Request Body Objects work #3761
Comments
@OAI/tsc review request: see above |
I expect some git spelunking (in an old swagger repo, perhaps)? might be needed to derive the original intent here. I agree it makes no sense at all - text/plain's serializer/deserializer is the identity function (and indeed my implementation has this hardcoded for 'text/*')! |
I do not believe this is a helpful example. I do not believe we have ever talked about how a JSON model should be serialized in text/plain payloads. We should make it a more useful example. |
I agree that this is not a helpful example and we should make it more useful. But I think there is a larger question here which is: how to interpret -- or whether to ignore -- In other words, I think that certain content types imply the schema -- maybe even impose a schema. I realize this is a much larger topic than just fixing an example, but shouldn't we address this somehow? |
@mikekistler I have had similar thoughts that there's a general topic here. I wasn't going to bring it up yet, but since you did (and I'm glad to hear someone else have this sort of thought), I have started a discussion on a registry for data modeling: Let's have the larger discussion there (including the idea of certain types implying or imposing a schema, which is an interesting frame that had not occurred to me) and focus on just this example (which it sounds like there is consensus to remove) here. |
I think the assessment is clear enough for me to remove the |
PR merged for 3.0.4 and ported to 3.1.1 via PR #3921! |
In the Request Body Examples section of both 3.0 and 3.1, the second example is as follows (JSON omitted for brevity):
A body parameter that is an array of string values:
This is identical to an example in the 2.0 spec, where the request body was treated as a parameter. I'm not entirely sure how it was supposed to be serialized even there, as the 3.x
style
andexplode
fields don't exist, but I definitely don't see how to serialize it in 3.0. There is no JSON Schema data model defined fortext/plain
, and nothing in the Request Body Object talks about how to serialize a list of values into plain text (Is it a comma-separated list? Is it one value per line?)What was this example trying to show, and how can we show it more clearly?
The text was updated successfully, but these errors were encountered: