v3.2: Provide guidance for the Set-Cookie response header

[handrews]

Partially addresses issue #1237

The Set-Cookie response header breaks the normal rules for headers with multiple values and requires special handling.

There are two options here:

1. Rework how we handle headers to accommodate Set-Cookie in a consistent manner
2. Treat Set-Cookie as a special case and define how it relates to normal behavior

Since RFC9110 §5.3 advises clients to treat Set-Cookie as a special case, I went with special-casing it. This assumes the approach to header serialization that is described in PR #4648 and discussed in one of its comment threads (specifically, that it does not include the header name which is required for it to be consistent with how style: "simple" and explode are treated elsewhere and are defined in RFC6570).

• 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]

With apologies to @philsturgeon for clearing his approval (its' set to automatically do that if anything changes) I realized we don't needallowReserved: true in that example (an earlier version I tried out did, and it was left over from that). And while I was at it I added a paragraph emphasizing that this only really matters if you need an intermedia multi-value single-string representation. If you just have an array of values and style: simple to map them to HTTP, they end results are the same as for other headers that support multiple values. Set-Cookie is only strange in that you cannot put multiple values on a single line.

[handrews]

OK apparently I was more out-of-it yesterday with this cold than I thought. Now I have added the commit that does things I mentioned in the last comment! 🤦

[lornajane]

I'm mostly in favour, with some minor editorial comments. Do we need to wait for the dataValue/serializedValue elements to resolve though? I see them in an example here.

[handrews]

@lornajane I have rewritten this to (hopefully) focus more on examples and less on explanations. This should also go well with PR #4800 which defines style example behavior in terms of whether the name is included in the example or not, and explains why it is for forms and is not for headers.

Meh... now there are conflicts, though, I will rebase and force-push, but it will be the same commits. It's probably best to just look at it fresh anyway as the rewrite commit on its own is noisier than just looking at it as one thing.

[lornajane]

I commented this somewhere else too: I don't think we have the serializedValue PR merged yet and I see this one uses the feature (and it's a good use of it!) so let's get that one in before we approve this one.

[ralfhandl]

+1 with one nit and two questions

[lornajane]

Thanks!

Changes were made