====== OpenAPI document structures ======

===== Sources =====
  * https://swagger.io/specification/
  * https://github.com/OAI/OpenAPI-Specification/blob/main/versions/

===== Structure by Version =====
surprising how much the structure can change between versions; here's a handful of versions to show that.  note the structure is the same for JSON and YAML versions.

==== 3.0.1 ====
  * schemas		: Map[string, Schema Object | Reference Object]
  * responses		: Map[string, Response Object | Reference Object]
  * parameters		: Map[string, Parameter Object | Reference Object]
  * examples		: Map[string, Example Object | Reference Object]
  * requestBodies	: Map[string, Request Body Object | Reference Object]
  * headers		: Map[string, Header Object | Reference Object]
  * securitySchemes	: Map[string, Security Scheme Object | Reference Object]
  * links		: Map[string, Link Object | Reference Object]
  * callbacks		: Map[string, Callback Object | Reference Object]

==== 3.0.2 ====
https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.2.md
  * openapi      : string ("3.0.2")
  * info         : Info
  * servers      : [Server]
  * paths        : Map[string, PathItem]
    * "/{path}" : PathItem
      * $ref : string
      * summary     : string
      * description : string
      * get         : Operation
        * tags         : string[]
        * summary      : string
        * description  : string
        * externalDocs : ExternalDocs
        * operationId  : string
        * parameters   : [Parameter | Reference]
          * name            : string
          * in              : string ("query", "header", "path", "cookie")
          * description     : string
          * required        : boolean
          * deprecated      : boolean
          * allowEmptyValue : boolean
          * style           : string
          * explode         : boolean (generate separate values for each item in array or object)
          * allowReserved   : boolean (don't encode reserved chars per RFC3986)
          * schema          : Schema | Reference
            * type                 : string
            * format               : string (values depend on type)
            * description          : string (can be in CommonMark syntax)
            * title                : string
            * multipleOf           : 
            * maximum              : 
            * exclusiveMaximum     : 
            * minimum              :
            * exclusiveMinimum     :
            * maxLength            :
            * minLength            :
            * pattern              : string (ECMA 262 regular expression)
            * maxItems             : int
            * minItems             : int
            * uniqueItems          : 
            * maxProperties        :
            * minProperties        :
            * required             : [string]
            * enum                 :
            * allOf                : Schema | Reference
            * oneOf                : Schema | Reference
            * anyOf                : Schema | Reference
            * not                  : Schema | Reference
            * items                : Schema | Reference
            * properties           : Schema | Reference (if type:"object")
            * additionalProperties : boolean | Object
            * default              : (depends on type)
            * discriminator        : Discriminator
            * readOnly             : boolean
            * writeOnly            : boolean
            * xml                  : XML
            * externalDocs         : ExternalDoc
            * example              : Any
            * deprecated           : boolean
          * example         : Any
          * examples        : Map[string, Example | Reference]
        * requestBody  : RequestBody | Reference
        * responses    : Responses
        * callbacks    : Map[string, Callback | Reference]
        * deprecated   : boolean
        * security     : [SecurityRequirement]
        * servers      : [Server]
      * put         : Operation
      * post        : Operation
      * delete      : Operation
      * options     : Operation
      * head        : Operation
      * patch       : Operation
      * trace       : Operation
      * servers     : [Server]
      * parameters  : Parameter | Reference
  * components   : Components
  * security     : [SecurityRequirement]
  * tags         : [Tag]
  * externalDocs : ExternalDocs


==== 3.0.3 ====
https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md
  * openapi	: string ("3.0.3")
  * info	: Info
    * title		: string
    * description	: string
    * termsOfService	: string
    * contact		: Contact
    * license		: License
    * version		: string
  * servers	: [Server]
    * url		: string
    * description	: string
    * variables		: Map[string, Server Variable] 
  * paths	: Paths
    * $ref	: string
    * summary	: string
    * description	: string
    * get		: Operation
    * put		: Operation
    * post		: Operation
    * delete		: Operation
    * options		: Operation
    * head		: Operation
    * patch		: Operation
    * trace		: Operation
    * servers		: [Server]
    * parameters	: [Parameter | Reference]
  * components	: Components
    * schemas		: Map[string, Schema|Reference]
    * responses		: Map[string, Response|Reference]
    * parameters	: Map[string, Parameter|Reference]
    * examples		: Map[string, Example|Reference]
    * requestBodies	: Map[string, RequestBody|Reference]
    * headers		: Map[string, Header|Reference]
    * securitySchemes	: Map[string, SecurityScheme|Reference]
    * links		: Map[string, Link|Reference]
    * callbacks		: Map[string, Callback|Reference]
  * security	: [Security Requirement]
    * <name>	: [string]
  * tags	: [Tag]
    * name		: string
    * description	: string
    * externalDocs	: ExternalDocumentation
  * externalDocs: ExternalDocumentation
    * description	: string
    * url		: string
 
==== 3.0.4 ====
  * same as 3.0.3!  (at least the top-level structure is)

==== 3.1.0 ====
  * openapi		: string
  * info		: Info Object
  * jsonSchemaDialect	: string
  * servers		: [Server Object]
  * paths		: Paths Object
  * webhooks		: Map[string, Path Item Object | Reference Object] ]
  * components		: Components Object
  * security		: [Security Requirement Object]
  * tags		: [Tag Object]
  * externalDocs	: External Documentation Object
 
==== 3.1.1 ====
  * same as 3.1.0 (at least the top-level structure is the same)

====== Gotchas ======
''$ref'' can NOT have ANY sibling elements so in order to, say, add a description to a field with a ''$ref''ed type you need to wrap the ref in a ''"allOf":[{}]''
e.g., instead of 
  "data": {
    "description": "List of Contacts",
    "$ref": "#/components/schemas/ContactArray"
  }
use
  "data": {
    "description": "List of Contacts",
    "allOf":[{"$ref": "#/components/schemas/ContactArray"}]
  }

otherwise the description will be lost because according to https://swagger.io/docs/specification/v3_0/using-ref/
> Any sibling elements of a ''$ref'' are ignored. This is because ''$ref'' works by replacing itself and everything on its level with the definition it is pointing at.