Differences

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

--- openapi [2025/02/04 16:35] – 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.3 ====
-https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md
-  * openapi	: string
-  * 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.