search

OAI / learn.openapis.org

OpenAPI - Getting started, and the specification explained
https://learn.openapis.org/
Creative Commons Attribution 4.0 International
112 stars 56 forks source link

Explanation of sibling refs #75

Open lornajane opened 7 months ago

lornajane commented 7 months ago

It would be helpful to get a short explanation of which contexts allow which siblings to a $ref as this causes quite a lot of confusion. There's a good comment from @handrews here: https://github.com/OAI/OpenAPI-Specification/discussions/3526#discussioncomment-8261253 which might give us a basis to start from.

handrews commented 7 months ago

This should be at least partially addressed by the table of reference behaviors in PR #80. I plan to expand on that in future PRs, but my first try got a little over-ambitious (and a little too rant-y) so this PR is relatively limited.