feat: add object descriptions and examples (#425)

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

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_]+$": {