feat: add object descriptions and examples (#425)

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>%0ACo-authored-by: Florent Baldino <[email protected]>%0ACo-authored-by: asyncapi-bot <[email protected]>

definitions/3.0.0/APIKeyHTTPSecurityScheme.json

@@ -8,30 +8,37 @@
   "properties": {
     "type": {
       "type": "string",
+      "description": "The type of the security scheme.",
       "enum": [
         "httpApiKey"
       ]
     },
     "name": {
-      "type": "string"
+      "type": "string",
+      "description": "The name of the header, query or cookie parameter to be used."
     },
     "in": {
       "type": "string",
+      "description": "The location of the API key",
       "enum": [
         "header",
         "query",
         "cookie"
       ]
     },
     "description": {
-      "type": "string"
+      "type": "string",
+      "description": "A short description for security scheme. CommonMark syntax MAY be used for rich text representation."
     }
   },
   "patternProperties": {
     "^x-[\\w\\d\\.\\x2d_]+$": {
       "$ref": "http://asyncapi.com/definitions/3.0.0/specificationExtension.json"
     }
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/3.0.0/APIKeyHTTPSecurityScheme.json"
+  },
   "additionalProperties": false,
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/3.0.0/APIKeyHTTPSecurityScheme.json"

definitions/3.0.0/BearerHTTPSecurityScheme.json

@@ -7,21 +7,25 @@
   "properties": {
     "scheme": {
       "type": "string",
+      "description": "The name of the HTTP Authorization scheme to be used in the Authorization header as defined in RFC7235.",
       "enum": [
         "bearer"
       ]
     },
     "bearerFormat": {
-      "type": "string"
+      "type": "string",
+      "description": "A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes."
     },
     "type": {
       "type": "string",
+      "description": "The type of the security scheme.",
       "enum": [
         "http"
       ]
     },
     "description": {
-      "type": "string"
+      "type": "string",
+      "description": "A short description for security scheme. CommonMark syntax MAY be used for rich text representation."
     }
   },
   "patternProperties": {

definitions/3.0.0/NonBearerHTTPSecurityScheme.json

@@ -4,6 +4,7 @@
     "properties": {
       "scheme": {
         "type": "string",
+        "description": "A short description for security scheme.",
         "enum": [
           "bearer"
         ]
@@ -17,13 +18,16 @@
   ],
   "properties": {
     "scheme": {
-      "type": "string"
+      "type": "string",
+      "description": "The name of the HTTP Authorization scheme to be used in the Authorization header as defined in RFC7235."
     },
     "description": {
-      "type": "string"
+      "type": "string",
+      "description": "A short description for security scheme."
     },
     "type": {
       "type": "string",
+      "description": "The type of the security scheme.",
       "enum": [
         "http"
       ]

definitions/3.0.0/Reference.json

@@ -1,13 +1,18 @@
 {
   "type": "object",
+  "description": "A simple object to allow referencing other components in the specification, internally and externally.",
   "required": [
     "$ref"
   ],
   "properties": {
     "$ref": {
+      "description": "The reference string.",
       "$ref": "http://asyncapi.com/definitions/3.0.0/ReferenceObject.json"
     }
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/3.0.0/ReferenceObject.json"
+  },
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/3.0.0/Reference.json"
 }

definitions/3.0.0/SaslGssapiSecurityScheme.json

@@ -6,19 +6,24 @@
   "properties": {
     "type": {
       "type": "string",
+      "description": "The type of the security scheme.",
       "enum": [
         "gssapi"
       ]
     },
     "description": {
-      "type": "string"
+      "type": "string",
+      "description": "A short description for security scheme."
     }
   },
   "patternProperties": {
     "^x-[\\w\\d\\.\\x2d_]+$": {
       "$ref": "http://asyncapi.com/definitions/3.0.0/specificationExtension.json"
     }
   },
+  "example": {
+    "$ref":  "http://asyncapi.com/examples/3.0.0/Sasl.json"
+  },
   "additionalProperties": false,
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/3.0.0/SaslGssapiSecurityScheme.json"

definitions/3.0.0/SaslPlainSecurityScheme.json

@@ -6,20 +6,25 @@
   "properties": {
     "type": {
       "type": "string",
+      "description": "The type of the security scheme. Valid values",
       "enum": [
         "plain"
       ]
     },
     "description": {
-      "type": "string"
+      "type": "string",
+      "description": "A short description for security scheme."
     }
   },
   "patternProperties": {
     "^x-[\\w\\d\\.\\x2d_]+$": {
       "$ref": "http://asyncapi.com/definitions/3.0.0/specificationExtension.json"
     }
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/3.0.0/Sasl.json"
+  },
   "additionalProperties": false,
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/3.0.0/SaslPlainSecurityScheme.json"
-}
+}

definitions/3.0.0/SaslScramSecurityScheme.json

@@ -6,21 +6,26 @@
   "properties": {
     "type": {
       "type": "string",
+      "description": "The type of the security scheme.",
       "enum": [
         "scramSha256",
         "scramSha512"
       ]
     },
     "description": {
-      "type": "string"
+      "type": "string",
+      "description": "A short description for security scheme."
     }
   },
   "patternProperties": {
     "^x-[\\w\\d\\.\\x2d_]+$": {
       "$ref": "http://asyncapi.com/definitions/3.0.0/specificationExtension.json"
     }
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/3.0.0/Sasl.json"
+  },
   "additionalProperties": false,
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/3.0.0/SaslScramSecurityScheme.json"
-}
+}

definitions/3.0.0/SecurityScheme.json

@@ -1,4 +1,5 @@
 {
+  "description": "Defines a security scheme that can be used by the operations.",
   "oneOf": [
     {
       "$ref": "http://asyncapi.com/definitions/3.0.0/userPassword.json"
@@ -28,6 +29,9 @@
       "$ref": "http://asyncapi.com/definitions/3.0.0/SaslSecurityScheme.json"
     }
   ],
+  "example": {
+    "$ref": "http://asyncapi.com/examples/3.0.0/SecurityScheme.json"
+  },
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/3.0.0/SecurityScheme.json"
 }

definitions/3.0.0/X509.json

@@ -19,7 +19,10 @@
       "$ref": "http://asyncapi.com/definitions/3.0.0/specificationExtension.json"
     }
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/3.0.0/X509.json"
+  },
   "additionalProperties": false,
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/3.0.0/X509.json"
-}
+}

definitions/3.0.0/anySchema.json

@@ -1,16 +1,16 @@
 {
-    "if": {
-        "required": [
-            "schema"
-        ]
-    },
-    "then": {
-        "$ref": "http://asyncapi.com/definitions/3.0.0/multiFormatSchema.json"
-    },
-    "else": {
-        "$ref": "http://asyncapi.com/definitions/3.0.0/schema.json"
-    },
-    "description": "An object representing either a schema or a multiFormatSchema based on the existence of the 'schema' property. If the property 'schema' is present, use the multi-format schema. Use the default AsyncAPI Schema otherwise.",
-    "$schema": "http://json-schema.org/draft-07/schema#",
-    "$id": "http://asyncapi.com/definitions/3.0.0/anySchema.json"
-}
+  "if": {
+    "required": [
+      "schema"
+    ]
+  },
+  "then": {
+    "$ref": "http://asyncapi.com/definitions/3.0.0/multiFormatSchema.json"
+  },
+  "else": {
+    "$ref": "http://asyncapi.com/definitions/3.0.0/schema.json"
+  },
+  "description": "An object representing either a schema or a multiFormatSchema based on the existence of the 'schema' property. If the property 'schema' is present, use the multi-format schema. Use the default AsyncAPI Schema otherwise.",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "http://asyncapi.com/definitions/3.0.0/anySchema.json"
+}

definitions/3.0.0/apiKey.json

@@ -7,27 +7,33 @@
   "properties": {
     "type": {
       "type": "string",
+      "description": "The type of the security scheme",
       "enum": [
         "apiKey"
       ]
     },
     "in": {
       "type": "string",
+      "description": " The location of the API key.",
       "enum": [
         "user",
         "password"
       ]
     },
     "description": {
-      "type": "string"
+      "type": "string",
+      "description": "A short description for security scheme. CommonMark syntax MAY be used for rich text representation."
     }
   },
   "patternProperties": {
     "^x-[\\w\\d\\.\\x2d_]+$": {
       "$ref": "http://asyncapi.com/definitions/3.0.0/specificationExtension.json"
     }
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/3.0.0/apiKey.json"
+  },
   "additionalProperties": false,
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/3.0.0/apiKey.json"
-}
+}

definitions/3.0.0/asymmetricEncryption.json

@@ -6,12 +6,14 @@
   "properties": {
     "type": {
       "type": "string",
+      "description": "The type of the security scheme.",
       "enum": [
         "asymmetricEncryption"
       ]
     },
     "description": {
-      "type": "string"
+      "type": "string",
+      "description": "A short description for security scheme."
     }
   },
   "patternProperties": {

definitions/3.0.0/asyncapi.json

@@ -31,7 +31,8 @@
       "$ref": "http://asyncapi.com/definitions/3.0.0/servers.json"
     },
     "defaultContentType": {
-      "type": "string"
+      "type": "string",
+      "description": "Default content type to use when encoding/decoding a message's payload."
     },
     "channels": {
       "$ref": "http://asyncapi.com/definitions/3.0.0/channels.json"

definitions/3.0.0/channel.json

@@ -1,5 +1,6 @@
 {
   "type": "object",
+  "description": "Describes a shared communication channel.",
   "additionalProperties": false,
   "patternProperties": {
     "^x-[\\w\\d\\.\\x2d_]+$": {
@@ -39,26 +40,27 @@
     },
     "tags": {
       "type": "array",
+      "description": "A list of tags for logical grouping of channels.",
       "items": {
         "oneOf": [
-          {
-            "$ref": "http://asyncapi.com/definitions/3.0.0/Reference.json"
-          },
-          {
-            "$ref": "http://asyncapi.com/definitions/3.0.0/tag.json"
-          }
-        ]
+  	  {
+	    "$ref": "http://asyncapi.com/definitions/3.0.0/Reference.json"
+	  },
+	  {
+  	    "$ref": "http://asyncapi.com/definitions/3.0.0/tag.json"
+	  }
+	]
       },
       "uniqueItems": true
     },
     "externalDocs": {
       "oneOf": [
         {
-          "$ref": "http://asyncapi.com/definitions/3.0.0/Reference.json"
-        },
-        {
-          "$ref": "http://asyncapi.com/definitions/3.0.0/externalDocs.json"
-        }
+  	  "$ref": "http://asyncapi.com/definitions/3.0.0/Reference.json"
+	},
+	{
+  	  "$ref": "http://asyncapi.com/definitions/3.0.0/externalDocs.json"
+	}
       ]
     },
     "bindings": {
@@ -72,6 +74,9 @@
       ]
     }
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/3.0.0/channel.json"
+  },
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/3.0.0/channel.json"
-}
+}

definitions/3.0.0/channelBindingsObject.json

@@ -1,5 +1,6 @@
 {
   "type": "object",
+  "description": "Map describing protocol-specific definitions for a channel.",
   "additionalProperties": false,
   "patternProperties": {
     "^x-[\\w\\d\\.\\x2d_]+$": {