OAI
v3.2: Explain Param/Header/Enc example serialization
NOTE: This is another PR split out from PR #4647, and makes significant changes to the style serialization for headers compared to that PR, and clarifies the other policies that already existed in PR #4647. This should be more consistent than what was there before, as I commented in the last call when I was unsure of header serialization.
The rules for this have not been clear, and are not always intuitive. This states and explains them directly and ensures that the Style Examples table matches the rules.
- [ ] schema changes are included in this pull request
- [ ] schema changes are needed for this pull request but not done yet
- [X] no schema changes are needed for this pull request
I have added updates to the Parameter and Header Object examples, as they fit here (and unlike with the Example Object, do not cause the diff to become unreadable).
If you would like more examples added, please help get this PR merged and then feel free to open further PRs. There are endless things we could add and I would like to get the existing things updated first.
I have also added a more complex header example, which @karenetheridge I think addresses your concern in this area.
Between the ongoing debate over serializedValue in the Example Object and the discussions here, I'm re-thinking how to explain this better. Putting this in draft for now- I might revive it or close it in favor of new PRs.