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

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.

• 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]

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

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

• same as 3.0.3! (at least the top-level structure is)

• 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

• same as 3.1.0 (at least the top-level structure is the same)

$ref can NOT have ANY sibling elements so in order to, say, add a description to a field with a $refed 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.