v3.2: Parameter and Header example updates

[handrews]

Note: This replaces the other half of PR #4673 (the first half being replaced by PR #4800), and updates parameter and header examples for PRs #4800, #4799., and #4802.

This updates for both the new example fields and for examples with content

• schema changes are included in this pull request
• schema changes are needed for this pull request but not done yet
• no schema changes are needed for this pull request

[handrews]

@ralfhandl the email notification contained this:

In src/oas.md:

@@ -1183,11 +1273,14 @@ content:
schema:
type: string
example: $.a.b[1:1]
+examples:
examples and example can currently only be used with schema, not with content, see https://github.com/OAI/OpenAPI-Specification/blob/v3.2-dev/src/oas.md#fixed-fields-for-use-with-content.

This affects multiple examples :sad:

but I don't see it now... was this just because I had split this from PR #4802? (and accidentally posted them in the wrong order...)

[ralfhandl]

Yes, I got confused for a minute and lost sight of the target picture.

[ralfhandl]

I don’t understand why the example does not match the pattern required by the schema.

[handrews]

LOL neither do I 🤦

[handrews]

@ralfhandl OK so it turns out the ETag header makes strange use of quotes, and I'm not really sure how to represent it. Here are examples from RFC9110:

ETag: "xyzzy"
ETag: W/"xyzzy"
ETag: ""

I was trying to ensure the first or third would be valid, but the second would not be. Which I guess means that unlike most headers where you strip the quotes (the quoted-string ABNF production), the quotes are significant in the ETag? I think?

So I think maybe this should be pattern: ^" and example: "\"xyzzy\""? Or maybe I should find a different example? I just want an example of a real header....

[handrews]

@ralfhandl I updated it with that approach and added a comment about the unusual quote use.... I am open to dropping this as too confusing but it's actually a semantically significant documentation use case.

[handrews]

(I have no idea if anyone would use this in an actual OAD, but it does tell you something useful).