More contentEncoding example improvements (from feedback) #4301
Conversation
handrews
added
examples
There was a problem hiding this comment.
Looks good! 👍
Thanks @handrews! I left one very minor suggestion.
Co-authored-by: Mike Kistler <mikekistler@microsoft.com>
There was a problem hiding this comment.
We use an inconsistent mix of single-quotes, double-quotes, backticks, and no decoration for field names and field values within YAML comments.
The style of the very first example looks best, so propagating its style to the other examples:
- double-quotes around field names
- no decoration of media type values
| @@ -1800,16 +1801,19 @@ requestBody: | |||
| schema: | |||
| type: object | |||
| properties: | |||
| # default for a string without `contentEncoding` is `text/plain` | |||
| # default content type for a string without `contentEncoding` | |||
There was a problem hiding this comment.
| # default content type for a string without `contentEncoding` | |
| # default content type for a string without "contentEncoding" |
Align with line 1749
| # default content type for a schema without `type` | ||
| # is `application/octet-stream` |
There was a problem hiding this comment.
| # default content type for a schema without `type` | |
| # is `application/octet-stream` | |
| # default content type for a schema without "type" | |
| # is application/octet-stream |
Align with lines 1749-1750
| # in the `items` subschema, which is an object here, | ||
| # so the default content type for each item is `application/json` |
There was a problem hiding this comment.
| # in the `items` subschema, which is an object here, | |
| # so the default content type for each item is `application/json` | |
| # in the "items" subschema, which is an object here, | |
| # so the default content type for each item is application/json |
| @@ -1833,7 +1837,7 @@ requestBody: | |||
| type: string | |||
| format: uuid | |||
|
|
|||
| # Encoding Object overrides the default `application/json` | |||
| # Encoding Object overrides the default `application/json` content type | |||
There was a problem hiding this comment.
| # Encoding Object overrides the default `application/json` content type | |
| # Encoding Object overrides the default application/json content type |
|
@ralfhandl we use backtics in YAML comments in many places. I would like to leave these as-is and then fix them throughout the document in a separate PR. There are some stylistic things to consider about the right way to handle this, including nested quotes of various sorts, so let's not introduce new variations without picking an overall style. |
|
@ralfhandl I have filed #4305 to track the further work. |
This incorporates ideas from @mikekistler that did not make it into #4294. Then I'll cherry-pick both commits over to v3.2-dev