Differences

This shows you the differences between two versions of the page.

--- openapi [2025/02/21 15:26] – added skeliton of 3.0.2 schema ron
+++ openapi [2025/04/13 16:23] (current) – removed ron
@@ Line 1: / Line 1: @@
-====== 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.