feat: add extensive descriptions and examples to the schema v2.6.0 (#394

)

README.md

@@ -114,6 +114,7 @@ If you are currently using version 3, check out [migration guideline to version
 This is the current project structure explained:
 
 - [./definitions](./definitions) - contain all the individual schemas that will automatically be bundled together to provide the schemas in [./schemas](./schemas).
+- [./examples](./examples) - contain most individual definition examples that will automatically be bundled together to provide example for each definition in the schemas in [./schemas](./schemas).
 - [./tools/bundler](./tools/bundler) - is the tool that bundles all the individual schemas together.
 - [./schemas](./schemas) - contain all automatically bundled and complete schemas for each AsyncAPI version. These schemas should **NOT** be manually changed as they are automatically generated. Any changes should be done in [./definitions](./definitions).
 
@@ -140,6 +141,8 @@ Where `x.x.x` is the new version you want to create.
 The manual process of creating a new version is to:
 1. Duplicate the latest version (`y.y.y`) under definitions (so we have the correct base to make changes from). 
 1. Rename the folder to the new version (`x.x.x`).
+1. Duplicate the latest version (`y.y.y`) under examples (so we have the correct base to make changes from).
+1. Rename the folder to the new version (`x.x.x`).
 1. Search and replace in the new duplicated folder for `y.y.y` and replace it with `x.x.x`.
 
 ### 2 Further steps

definitions/2.6.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."
     }
   },
   "patternProperties": {
     "^x-[\\w\\d\\.\\x2d_]+$": {
       "$ref": "http://asyncapi.com/definitions/2.6.0/specificationExtension.json"
     }
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/APIKeyHTTPSecurityScheme.json"
+  },
   "additionalProperties": false,
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/2.6.0/APIKeyHTTPSecurityScheme.json"

definitions/2.6.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."
     },
     "type": {
       "type": "string",
+      "description": "The type of the security scheme. ",
       "enum": [
         "http"
       ]
     },
     "description": {
-      "type": "string"
+      "type": "string",
+      "description": "A short description for security scheme."
     }
   },
   "patternProperties": {

definitions/2.6.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/2.6.0/ReferenceObject.json

@@ -1,6 +1,10 @@
 {
   "type": "string",
+  "description": "A simple object to allow referencing other components in the specification, internally and externally.",
   "format": "uri-reference",
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/ReferenceObject.json"
+  },
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/2.6.0/ReferenceObject.json"
 }

definitions/2.6.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/2.6.0/specificationExtension.json"
     }
   },
+  "example": {
+    "$ref":  "http://asyncapi.com/examples/2.6.0/Sasl.json"
+  },
   "additionalProperties": false,
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/2.6.0/SaslGssapiSecurityScheme.json"

definitions/2.6.0/SaslPlainSecurityScheme.json

@@ -6,19 +6,24 @@
   "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/2.6.0/specificationExtension.json"
     }
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/Sasl.json"
+  },
   "additionalProperties": false,
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/2.6.0/SaslPlainSecurityScheme.json"

definitions/2.6.0/SaslScramSecurityScheme.json

@@ -6,20 +6,25 @@
   "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/2.6.0/specificationExtension.json"
     }
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/Sasl.json"
+  },
   "additionalProperties": false,
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/2.6.0/SaslScramSecurityScheme.json"

definitions/2.6.0/SecurityRequirement.json

@@ -1,12 +1,16 @@
 {
   "type": "object",
+  "description": "Lists of the required security schemes that can be used to execute an operation",
   "additionalProperties": {
     "type": "array",
     "items": {
       "type": "string"
     },
     "uniqueItems": true
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/SecurityRequirement.json"
+  },
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/2.6.0/SecurityRequirement.json"
 }

definitions/2.6.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/2.6.0/userPassword.json"
@@ -28,6 +29,9 @@
       "$ref": "http://asyncapi.com/definitions/2.6.0/SaslSecurityScheme.json"
     }
   ],
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/SecurityScheme.json"
+  },
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/2.6.0/SecurityScheme.json"
 }

definitions/2.6.0/X509.json

@@ -8,17 +8,22 @@
       "type": "string",
       "enum": [
         "X509"
-      ]
+      ],
+      "description": "The type of the security scheme."
     },
     "description": {
-      "type": "string"
+      "type": "string",
+      "description": "A short description for security scheme."
     }
   },
   "patternProperties": {
     "^x-[\\w\\d\\.\\x2d_]+$": {
       "$ref": "http://asyncapi.com/definitions/2.6.0/specificationExtension.json"
     }
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/X509.json"
+  },
   "additionalProperties": false,
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/2.6.0/X509.json"

definitions/2.6.0/apiKey.json

@@ -7,26 +7,32 @@
   "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."
     }
   },
   "patternProperties": {
     "^x-[\\w\\d\\.\\x2d_]+$": {
       "$ref": "http://asyncapi.com/definitions/2.6.0/specificationExtension.json"
     }
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/apiKey.json"
+  },
   "additionalProperties": false,
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/2.6.0/apiKey.json"

definitions/2.6.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/2.6.0/bindingsObject.json

@@ -1,5 +1,6 @@
 {
   "type": "object",
+  "description": "Map describing protocol-specific definitions for a server.",
   "additionalProperties": true,
   "properties": {
     "http": {},

definitions/2.6.0/channelItem.json

@@ -1,5 +1,6 @@
 {
   "type": "object",
+  "description": "Describes the operations available on a single channel.",
   "additionalProperties": false,
   "patternProperties": {
     "^x-[\\w\\d\\.\\x2d_]+$": {
@@ -39,6 +40,9 @@
       "$ref": "http://asyncapi.com/definitions/2.6.0/bindingsObject.json"
     }
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/channelItem.json"
+  },
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/2.6.0/channelItem.json"
 }

definitions/2.6.0/channels.json

@@ -1,5 +1,6 @@
 {
   "type": "object",
+  "description": "Holds the relative paths to the individual channel and their operations. Channel paths are relative to servers.",
   "propertyNames": {
     "type": "string",
     "format": "uri-template",
@@ -8,6 +9,9 @@
   "additionalProperties": {
     "$ref": "http://asyncapi.com/definitions/2.6.0/channelItem.json"
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/channels.json"
+  },
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/2.6.0/channels.json"
 }

definitions/2.6.0/components.json

@@ -1,6 +1,6 @@
 {
   "type": "object",
-  "description": "An object to hold a set of reusable objects for different aspects of the AsyncAPI Specification.",
+  "description": "Holds a set of reusable objects for different aspects of the AsyncAPI specification. All objects defined within the components object will have no effect on the API unless they are explicitly referenced from properties outside the components object.",
   "additionalProperties": false,
   "patternProperties": {
     "^x-[\\w\\d\\.\\x2d_]+$": {
@@ -93,6 +93,9 @@
       }
     }
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/components.json"
+  },
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/2.6.0/components.json"
 }

definitions/2.6.0/contact.json

@@ -1,6 +1,6 @@
 {
   "type": "object",
-  "description": "Contact information for the owners of the API.",
+  "description": "Contact information for the exposed API.",
   "additionalProperties": false,
   "properties": {
     "name": {
@@ -23,6 +23,9 @@
       "$ref": "http://asyncapi.com/definitions/2.6.0/specificationExtension.json"
     }
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/contact.json"
+  },
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/2.6.0/contact.json"
 }