OpenAPI v3.1 Ref Sibling Changes

[philsturgeon]

I see #794 is making some progress, and there might be a few improvements that can be made once thats done.

Main thing I'm noticing going through the docs is that you won't need to throw away "ref siblings" anymore, so this warning on the descriptions docs could go away for OAS 3.1 users.

You may expect to see a description for the id if you set one. However, since it'll be transformed to a reference to the UUID schema, the description must be ignored, since any properties that are placed next to $ref (OpenAPI's mechanism to link to the UUID schema) must be ignored.

That means the description from UUID could be popped into the description for id. Same sort of thing with examples being merged from the referenced item.

See if any of this is handy: https://learn.openapis.org/upgrading/v3.0-to-v3.1.html

I'll pop in anything else I notice as I go. Thanks for making this great tool!

[github-actions]

Hello there philsturgeon 👋

Thank you for opening your very first issue in this project.

We will try to get back to you as soon as we can.👀