v3.2: Allow Parameter/Header "examples" field with "content" field #4648
Conversation
handrews
added
param serialization
handrews
changed the title
handrews
changed the title
Parameter and Header serialization is complex, particularly when using the `content` field to use a Media Type Object. In such scenarios, the serialization occurs in two steps: The first step is to serialize the data to the media type, which can be captured by the `examples` field of the Media Type Object. The second is the encoding/escaping of the media type document for use in a URI, HTTP header, or other location with its own rules. Sometimes the part needing illustration with an example is at one level, sometimes at another, and sometimes it is helpful to show both. For simplicity, the "data" examples are always treated as the overall input data, so they would be the same at both levels. This is also because it is not always possible to show each step, particularly when there are binary serializations. This allows showing either step (or both steps) with both data and serialization, depending on what makes sense for the use case.
Co-authored-by: Karen Etheridge <[email protected]>
handrews
force-pushed
the
content-examples
branch
from
ae592e3 to
e9f1322
Compare
|
Rebased with only minor conflicts (Git getting confused by adjacent changes, not multiple changes to the same line). |
| examples: | ||
| spacesAndPluses: | ||
| description: Note handling of spaces and "+" per media type. | ||
| dataValue: | ||
| foo: a + b | ||
| bar: true | ||
| serializedValue: | ||
| foo=a+%2B+b&bar=true | ||
| examples: | ||
| spacesAndPluses: | ||
| description: | | ||
| Note that no additional percent encoding is done, as this | ||
| media type is URI query string-ready by definition. | ||
| dataValue: | ||
| foo: a + b | ||
| bar: true | ||
| serializedValue: foo=a+%2B+b&bar=true |
There was a problem hiding this comment.
Why twice examples with the same data and serialized values? Please add explanation what this is supposed to demonstrate, or reduce to one occurrence of examples.
There was a problem hiding this comment.
@ralfhandl As noted on lines 1172-1174, the point of this is to show that you do not re-percent-encode the already-percent-encoded application/x-www-form-urlencoded media type. This is in contrast to other media types that would not be percent-encoded in the Media Type Object's examples, but would be percent-encoded in the Parameter Object's examples, which is shown in the next example.
I will figure out a better way to frame / show this.
| examples: | ||
| TwoNoFlag: | ||
| description: Serialize with minimized whitespace | ||
| dataValue: { | ||
| "numbers": [1, 2], | ||
| "flag": null | ||
| } | ||
| serializedValue: '{"numbers":[1,2],"flag":null}' |
There was a problem hiding this comment.
What's the point of this inner examples? As an example for the parameter it is useless and misleading as it shows a serialized value that is not valid for the paramter. It is technically allowed there, and valid for the schema without its context, and also "academic" and not a best practice we want people to adopt.
There was a problem hiding this comment.
It is correct for the Media Type Object, which is the context of this Example Object. It shows an intermediate serialization step. It pairs with the previous example, but I will work out a better way to present this.
NOTE: This is a companion to PR #4647 that just adds to where we can use Example Objects as the second part of the three-part proposal. It is written assuming that PR would be merged because that makes the benefit more clear, although it could technically be done even without that PR. But that would be less useful since tools do not support the serialization rules for the old example fields.
Parameter and Header serialization is complex, particularly when using the
contentfield to use a Media Type Object.In such scenarios, the serialization occurs in two steps: The first step is to serialize the data to the media type, which can be captured by the
examplesfield of the Media Type Object.The second is the encoding/escaping of the media type document for use in a URI, HTTP header, or other location with its own rules.
Sometimes the part needing illustration with an example is at one level, sometimes at another, and sometimes it is helpful to show both.
For simplicity, the "data" examples are always treated as the overall input data, so they would be the same at both levels. This is also because it is not always possible to show each step, particularly when there are binary serializations. This allows showing either step (or both steps) with both data and serialization, depending on what makes sense for the use case.