feat: additional documentation & examples for $ref

[LukeHagar]

Examples of local and remote file references

Complex examples using file references in:

• parameters
• request bodies
• error types
• components
• security schemas

Examples of circular file references
Shared references between multiple specifications
Examples using references in allOf, anyOf, oneOf

Best practices for using references:

• What should the structure be of the file you are referencing?
  • for parameters
  • for request bodies
  • for error types
  • for components
  • for security schemas
• References in arrays
• References in discriminators

[LukeHagar]

For inspiration:
https://swagger.io/docs/specification/using-ref/

Specifically sections like:

• $ref Syntax
• $ref and Sibling Elements