diff --git a/README.md b/README.md index d4ecdb84..97315fb2 100644 --- a/README.md +++ b/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 diff --git a/definitions/2.6.0/APIKeyHTTPSecurityScheme.json b/definitions/2.6.0/APIKeyHTTPSecurityScheme.json index 12773091..b0eb58fc 100644 --- a/definitions/2.6.0/APIKeyHTTPSecurityScheme.json +++ b/definitions/2.6.0/APIKeyHTTPSecurityScheme.json @@ -8,15 +8,18 @@ "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", @@ -24,7 +27,8 @@ ] }, "description": { - "type": "string" + "type": "string", + "description": "A short description for security scheme." } }, "patternProperties": { @@ -32,6 +36,9 @@ "$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" diff --git a/definitions/2.6.0/BearerHTTPSecurityScheme.json b/definitions/2.6.0/BearerHTTPSecurityScheme.json index 3eba87ac..edede767 100644 --- a/definitions/2.6.0/BearerHTTPSecurityScheme.json +++ b/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": { diff --git a/definitions/2.6.0/NonBearerHTTPSecurityScheme.json b/definitions/2.6.0/NonBearerHTTPSecurityScheme.json index a815a1e5..45cf74d7 100644 --- a/definitions/2.6.0/NonBearerHTTPSecurityScheme.json +++ b/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" ] diff --git a/definitions/2.6.0/ReferenceObject.json b/definitions/2.6.0/ReferenceObject.json index 82075d2e..c8016b37 100644 --- a/definitions/2.6.0/ReferenceObject.json +++ b/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" } \ No newline at end of file diff --git a/definitions/2.6.0/SaslGssapiSecurityScheme.json b/definitions/2.6.0/SaslGssapiSecurityScheme.json index 8d58c9d1..7d880921 100644 --- a/definitions/2.6.0/SaslGssapiSecurityScheme.json +++ b/definitions/2.6.0/SaslGssapiSecurityScheme.json @@ -6,12 +6,14 @@ "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": { @@ -19,6 +21,9 @@ "$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" diff --git a/definitions/2.6.0/SaslPlainSecurityScheme.json b/definitions/2.6.0/SaslPlainSecurityScheme.json index 766428f7..a830e8fa 100644 --- a/definitions/2.6.0/SaslPlainSecurityScheme.json +++ b/definitions/2.6.0/SaslPlainSecurityScheme.json @@ -6,12 +6,14 @@ "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": { @@ -19,6 +21,9 @@ "$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" diff --git a/definitions/2.6.0/SaslScramSecurityScheme.json b/definitions/2.6.0/SaslScramSecurityScheme.json index a60641c5..8cfaad36 100644 --- a/definitions/2.6.0/SaslScramSecurityScheme.json +++ b/definitions/2.6.0/SaslScramSecurityScheme.json @@ -6,13 +6,15 @@ "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": { @@ -20,6 +22,9 @@ "$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" diff --git a/definitions/2.6.0/SecurityRequirement.json b/definitions/2.6.0/SecurityRequirement.json index 5579d55b..2f420459 100644 --- a/definitions/2.6.0/SecurityRequirement.json +++ b/definitions/2.6.0/SecurityRequirement.json @@ -1,5 +1,6 @@ { "type": "object", + "description": "Lists of the required security schemes that can be used to execute an operation", "additionalProperties": { "type": "array", "items": { @@ -7,6 +8,9 @@ }, "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" } \ No newline at end of file diff --git a/definitions/2.6.0/SecurityScheme.json b/definitions/2.6.0/SecurityScheme.json index 3c8bc421..33cc504f 100644 --- a/definitions/2.6.0/SecurityScheme.json +++ b/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" } \ No newline at end of file diff --git a/definitions/2.6.0/X509.json b/definitions/2.6.0/X509.json index bcc1b8fb..c936b444 100644 --- a/definitions/2.6.0/X509.json +++ b/definitions/2.6.0/X509.json @@ -8,10 +8,12 @@ "type": "string", "enum": [ "X509" - ] + ], + "description": "The type of the security scheme." }, "description": { - "type": "string" + "type": "string", + "description": "A short description for security scheme." } }, "patternProperties": { @@ -19,6 +21,9 @@ "$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" diff --git a/definitions/2.6.0/apiKey.json b/definitions/2.6.0/apiKey.json index d5cc1f00..555c5cc1 100644 --- a/definitions/2.6.0/apiKey.json +++ b/definitions/2.6.0/apiKey.json @@ -7,19 +7,22 @@ "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": { @@ -27,6 +30,9 @@ "$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" diff --git a/definitions/2.6.0/asymmetricEncryption.json b/definitions/2.6.0/asymmetricEncryption.json index b4840576..9fdc6839 100644 --- a/definitions/2.6.0/asymmetricEncryption.json +++ b/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": { diff --git a/definitions/2.6.0/bindingsObject.json b/definitions/2.6.0/bindingsObject.json index a9c67756..611a87b8 100644 --- a/definitions/2.6.0/bindingsObject.json +++ b/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": {}, diff --git a/definitions/2.6.0/channelItem.json b/definitions/2.6.0/channelItem.json index 4fb12585..75487cad 100644 --- a/definitions/2.6.0/channelItem.json +++ b/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" } \ No newline at end of file diff --git a/definitions/2.6.0/channels.json b/definitions/2.6.0/channels.json index edd1b3c0..aec983ab 100644 --- a/definitions/2.6.0/channels.json +++ b/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" } \ No newline at end of file diff --git a/definitions/2.6.0/components.json b/definitions/2.6.0/components.json index 4e3b1b28..1da80623 100644 --- a/definitions/2.6.0/components.json +++ b/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" } \ No newline at end of file diff --git a/definitions/2.6.0/contact.json b/definitions/2.6.0/contact.json index 25f6e180..0f63b39a 100644 --- a/definitions/2.6.0/contact.json +++ b/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" } \ No newline at end of file diff --git a/definitions/2.6.0/correlationId.json b/definitions/2.6.0/correlationId.json index 1c5df58d..96e680af 100644 --- a/definitions/2.6.0/correlationId.json +++ b/definitions/2.6.0/correlationId.json @@ -1,5 +1,6 @@ { "type": "object", + "description": "An object that specifies an identifier at design time that can used for message tracing and correlation.", "required": [ "location" ], @@ -20,6 +21,9 @@ "pattern": "^\\$message\\.(header|payload)#(\\/(([^\\/~])|(~[01]))*)*" } }, + "example": { + "$ref": "http://asyncapi.com/examples/2.6.0/correlationId.json" + }, "$schema": "http://json-schema.org/draft-07/schema#", "$id": "http://asyncapi.com/definitions/2.6.0/correlationId.json" } \ No newline at end of file diff --git a/definitions/2.6.0/externalDocs.json b/definitions/2.6.0/externalDocs.json index c51a02af..b760c0cf 100644 --- a/definitions/2.6.0/externalDocs.json +++ b/definitions/2.6.0/externalDocs.json @@ -1,17 +1,17 @@ { "type": "object", "additionalProperties": false, - "description": "information about external documentation", - "required": [ - "url" - ], + "description": "Allows referencing an external resource for extended documentation.", + "required": ["url"], "properties": { "description": { - "type": "string" + "type": "string", + "description": "A short description of the target documentation." }, "url": { "type": "string", - "format": "uri" + "format": "uri", + "description": "The URL for the target documentation. This MUST be in the form of an absolute URL." } }, "patternProperties": { @@ -19,6 +19,9 @@ "$ref": "http://asyncapi.com/definitions/2.6.0/specificationExtension.json" } }, + "example": { + "$ref": "http://asyncapi.com/examples/2.6.0/externalDocs.json" + }, "$schema": "http://json-schema.org/draft-07/schema#", "$id": "http://asyncapi.com/definitions/2.6.0/externalDocs.json" } \ No newline at end of file diff --git a/definitions/2.6.0/info.json b/definitions/2.6.0/info.json index 93f5d023..2ad3c706 100644 --- a/definitions/2.6.0/info.json +++ b/definitions/2.6.0/info.json @@ -1,6 +1,6 @@ { "type": "object", - "description": "General information about the API.", + "description": "The object provides metadata about the API. The metadata can be used by the clients if needed.", "required": [ "version", "title" @@ -36,6 +36,9 @@ "$ref": "http://asyncapi.com/definitions/2.6.0/license.json" } }, + "example": { + "$ref": "http://asyncapi.com/examples/2.6.0/info.json" + }, "$schema": "http://json-schema.org/draft-07/schema#", "$id": "http://asyncapi.com/definitions/2.6.0/info.json" } \ No newline at end of file diff --git a/definitions/2.6.0/license.json b/definitions/2.6.0/license.json index 8bd72537..1021a7bf 100644 --- a/definitions/2.6.0/license.json +++ b/definitions/2.6.0/license.json @@ -3,6 +3,7 @@ "required": [ "name" ], + "description": "License information for the exposed API.", "additionalProperties": false, "properties": { "name": { @@ -20,6 +21,9 @@ "$ref": "http://asyncapi.com/definitions/2.6.0/specificationExtension.json" } }, + "example": { + "$ref": "http://asyncapi.com/examples/2.6.0/license.json" + }, "$schema": "http://json-schema.org/draft-07/schema#", "$id": "http://asyncapi.com/definitions/2.6.0/license.json" } \ No newline at end of file diff --git a/definitions/2.6.0/message.json b/definitions/2.6.0/message.json index 226286cb..8069c607 100644 --- a/definitions/2.6.0/message.json +++ b/definitions/2.6.0/message.json @@ -1,4 +1,5 @@ { + "description": "Describes a message received on a given channel and operation.", "oneOf": [ { "$ref": "http://asyncapi.com/definitions/2.6.0/Reference.json" @@ -93,6 +94,7 @@ }, "examples": { "type": "array", + "description": "List of examples.", "items": { "type": "object", "additionalProperties": false, @@ -114,9 +116,12 @@ "description": "A brief summary of the message example." }, "headers": { - "type": "object" + "type": "object", + "description": "Schema definition of the application headers." }, - "payload": {} + "payload": { + "description": "Definition of the message payload. It can be of any type" + } } } }, @@ -268,6 +273,9 @@ ] } ], + "example": { + "$ref": "http://asyncapi.com/examples/2.6.0/message.json" + }, "$schema": "http://json-schema.org/draft-07/schema#", "$id": "http://asyncapi.com/definitions/2.6.0/message.json" } diff --git a/definitions/2.6.0/messageTrait.json b/definitions/2.6.0/messageTrait.json index 6b8bc079..cbdf2bcb 100644 --- a/definitions/2.6.0/messageTrait.json +++ b/definitions/2.6.0/messageTrait.json @@ -1,5 +1,6 @@ { "type": "object", + "description": "Describes a trait that MAY be applied to a Message Object.", "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { @@ -8,12 +9,15 @@ }, "properties": { "schemaFormat": { - "type": "string" + "type": "string", + "description": "A string containing the name of the schema format/language used to define the message payload." }, "contentType": { - "type": "string" + "type": "string", + "description": "The content type to use when encoding/decoding a message's payload." }, "headers": { + "description": "Schema definition of the application headers.", "allOf": [ { "$ref": "http://asyncapi.com/definitions/2.6.0/schema.json" @@ -28,9 +32,11 @@ ] }, "messageId": { - "type": "string" + "type": "string", + "description": "Unique string used to identify the message. The id MUST be unique among all messages described in the API." }, "correlationId": { + "description": "Definition of the correlation ID used for message tracing or matching.", "oneOf": [ { "$ref": "http://asyncapi.com/definitions/2.6.0/Reference.json" @@ -42,6 +48,7 @@ }, "tags": { "type": "array", + "description": "A list of tags for logical grouping and categorization of messages.", "items": { "$ref": "http://asyncapi.com/definitions/2.6.0/tag.json" }, @@ -72,14 +79,44 @@ }, "examples": { "type": "array", + "description": "List of examples.", "items": { - "type": "object" + "type": "object", + "additionalProperties": false, + "anyOf": [ + { + "required": ["payload"] + }, + { + "required": ["headers"] + } + ], + "properties": { + "name": { + "type": "string", + "description": "Machine readable name of the message example." + }, + "summary": { + "type": "string", + "description": "A brief summary of the message example." + }, + "headers": { + "type": "object", + "description": "Schema definition of the application headers." + }, + "payload": { + "description": "Definition of the message payload. It can be of any type" + } + } } }, "bindings": { "$ref": "http://asyncapi.com/definitions/2.6.0/bindingsObject.json" } }, + "example": { + "$ref": "http://asyncapi.com/examples/2.6.0/messageTrait.json" + }, "$schema": "http://json-schema.org/draft-07/schema#", "$id": "http://asyncapi.com/definitions/2.6.0/messageTrait.json" -} \ No newline at end of file +} diff --git a/definitions/2.6.0/oauth2Flow.json b/definitions/2.6.0/oauth2Flow.json index dca2e747..9aa287a0 100644 --- a/definitions/2.6.0/oauth2Flow.json +++ b/definitions/2.6.0/oauth2Flow.json @@ -1,19 +1,24 @@ { "type": "object", + "description": "Configuration details for a supported OAuth Flow", "properties": { "authorizationUrl": { "type": "string", - "format": "uri" + "format": "uri", + "description": "The authorization URL to be used for this flow. This MUST be in the form of an absolute URL." }, "tokenUrl": { "type": "string", - "format": "uri" + "format": "uri", + "description": "The token URL to be used for this flow. This MUST be in the form of an absolute URL." }, "refreshUrl": { "type": "string", - "format": "uri" + "format": "uri", + "description": "The URL to be used for obtaining refresh tokens. This MUST be in the form of an absolute URL." }, "scopes": { + "description": "The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it.", "$ref": "http://asyncapi.com/definitions/2.6.0/oauth2Scopes.json" } }, @@ -23,6 +28,9 @@ } }, "additionalProperties": false, + "example": { + "$ref": "http://asyncapi.com/examples/2.6.0/oauth2Flow.json" + }, "$schema": "http://json-schema.org/draft-07/schema#", "$id": "http://asyncapi.com/definitions/2.6.0/oauth2Flow.json" } \ No newline at end of file diff --git a/definitions/2.6.0/oauth2Flows.json b/definitions/2.6.0/oauth2Flows.json index 8420d253..d83ec2e2 100644 --- a/definitions/2.6.0/oauth2Flows.json +++ b/definitions/2.6.0/oauth2Flows.json @@ -1,5 +1,6 @@ { "type": "object", + "description": "Allows configuration of the supported OAuth Flows.", "required": [ "type", "flows" @@ -7,17 +8,20 @@ "properties": { "type": { "type": "string", + "description": "A short description for security scheme.", "enum": [ "oauth2" ] }, "description": { - "type": "string" + "type": "string", + "description": "A short description for security scheme." }, "flows": { "type": "object", "properties": { "implicit": { + "description": "Configuration for the OAuth Implicit flow.", "allOf": [ { "$ref": "http://asyncapi.com/definitions/2.6.0/oauth2Flow.json" @@ -38,6 +42,7 @@ ] }, "password": { + "description": "Configuration for the OAuth Resource Owner Protected Credentials flow.", "allOf": [ { "$ref": "http://asyncapi.com/definitions/2.6.0/oauth2Flow.json" @@ -58,6 +63,7 @@ ] }, "clientCredentials": { + "description": "Configuration for the OAuth Client Credentials flow.", "allOf": [ { "$ref": "http://asyncapi.com/definitions/2.6.0/oauth2Flow.json" @@ -78,6 +84,7 @@ ] }, "authorizationCode": { + "description": "Configuration for the OAuth Authorization Code flow.", "allOf": [ { "$ref": "http://asyncapi.com/definitions/2.6.0/oauth2Flow.json" diff --git a/definitions/2.6.0/operation.json b/definitions/2.6.0/operation.json index 42611325..ffcd3dce 100644 --- a/definitions/2.6.0/operation.json +++ b/definitions/2.6.0/operation.json @@ -1,5 +1,6 @@ { "type": "object", + "description": "Describes a publish or a subscribe operation. This provides a place to document how and why messages are sent and received.", "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { @@ -9,6 +10,7 @@ "properties": { "traits": { "type": "array", + "description": "A list of traits to apply to the operation object.", "items": { "oneOf": [ { @@ -21,19 +23,23 @@ } }, "summary": { - "type": "string" + "type": "string", + "description": "A short summary of what the operation is about." }, "description": { - "type": "string" + "type": "string", + "description": "A verbose explanation of the operation." }, "security": { "type": "array", + "description": "A declaration of which security mechanisms are associated with this operation.", "items": { "$ref": "http://asyncapi.com/definitions/2.6.0/SecurityRequirement.json" } }, "tags": { "type": "array", + "description": "A list of tags for logical grouping and categorization of operations.", "items": { "$ref": "http://asyncapi.com/definitions/2.6.0/tag.json" }, @@ -52,6 +58,9 @@ "$ref": "http://asyncapi.com/definitions/2.6.0/message.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/operation.json" } diff --git a/definitions/2.6.0/operationTrait.json b/definitions/2.6.0/operationTrait.json index e4a94062..ca701a83 100644 --- a/definitions/2.6.0/operationTrait.json +++ b/definitions/2.6.0/operationTrait.json @@ -1,5 +1,6 @@ { "type": "object", + "description": "Describes a trait that MAY be applied to an Operation Object.", "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { @@ -8,13 +9,16 @@ }, "properties": { "summary": { - "type": "string" + "type": "string", + "description": "A short summary of what the operation is about." }, "description": { - "type": "string" + "type": "string", + "description": "A verbose explanation of the operation." }, "tags": { "type": "array", + "description": "A list of tags for logical grouping and categorization of operations.", "items": { "$ref": "http://asyncapi.com/definitions/2.6.0/tag.json" }, @@ -24,10 +28,12 @@ "$ref": "http://asyncapi.com/definitions/2.6.0/externalDocs.json" }, "operationId": { - "type": "string" + "type": "string", + "description": "Unique string used to identify the operation. The id MUST be unique among all operations described in the API." }, "security": { "type": "array", + "description": "A declaration of which security mechanisms are associated with this operation. ", "items": { "$ref": "http://asyncapi.com/definitions/2.6.0/SecurityRequirement.json" } @@ -36,6 +42,9 @@ "$ref": "http://asyncapi.com/definitions/2.6.0/bindingsObject.json" } }, + "example": { + "$ref": "http://asyncapi.com/examples/2.6.0/operationTrait.json" + }, "$schema": "http://json-schema.org/draft-07/schema#", "$id": "http://asyncapi.com/definitions/2.6.0/operationTrait.json" } \ No newline at end of file diff --git a/definitions/2.6.0/parameter.json b/definitions/2.6.0/parameter.json index 745cd03a..529abce9 100644 --- a/definitions/2.6.0/parameter.json +++ b/definitions/2.6.0/parameter.json @@ -1,4 +1,5 @@ { + "description": "Describes a parameter included in a channel name.", "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { @@ -19,6 +20,9 @@ "pattern": "^\\$message\\.(header|payload)#(\\/(([^\\/~])|(~[01]))*)*" } }, + "example": { + "$ref": "http://asyncapi.com/examples/2.6.0/parameter.json" + }, "$schema": "http://json-schema.org/draft-07/schema#", "$id": "http://asyncapi.com/definitions/2.6.0/parameter.json" } \ No newline at end of file diff --git a/definitions/2.6.0/parameters.json b/definitions/2.6.0/parameters.json index a8f38364..20bcf79e 100644 --- a/definitions/2.6.0/parameters.json +++ b/definitions/2.6.0/parameters.json @@ -1,5 +1,6 @@ { "type": "object", + "description": "JSON objects describing reusable channel parameters.", "additionalProperties": { "oneOf": [ { @@ -10,7 +11,9 @@ } ] }, - "description": "JSON objects describing re-usable channel parameters.", + "example": { + "$ref": "http://asyncapi.com/examples/2.6.0/parameters.json" + }, "$schema": "http://json-schema.org/draft-07/schema#", "$id": "http://asyncapi.com/definitions/2.6.0/parameters.json" } \ No newline at end of file diff --git a/definitions/2.6.0/schema.json b/definitions/2.6.0/schema.json index c6f2fa8d..dffef6b9 100644 --- a/definitions/2.6.0/schema.json +++ b/definitions/2.6.0/schema.json @@ -1,4 +1,5 @@ { + "description": "The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays.", "allOf": [ { "$ref": "http://json-schema.org/draft-07/schema#" @@ -81,18 +82,24 @@ "$ref": "http://asyncapi.com/definitions/2.6.0/schema.json" }, "discriminator": { - "type": "string" + "type": "string", + "description": "Adds support for polymorphism. The discriminator is the schema property name that is used to differentiate between other schema that inherit this schema. " }, "externalDocs": { + "description": "Additional external documentation for this schema.", "$ref": "http://asyncapi.com/definitions/2.6.0/externalDocs.json" }, "deprecated": { "type": "boolean", - "default": false + "default": false, + "description": "Specifies that a schema is deprecated and SHOULD be transitioned out of usage" } } } ], + "example": { + "$ref": "http://asyncapi.com/examples/2.6.0/schema.json" + }, "$schema": "http://json-schema.org/draft-07/schema#", "$id": "http://asyncapi.com/definitions/2.6.0/schema.json" } \ No newline at end of file diff --git a/definitions/2.6.0/server.json b/definitions/2.6.0/server.json index 1cc26d3b..8741900c 100644 --- a/definitions/2.6.0/server.json +++ b/definitions/2.6.0/server.json @@ -1,6 +1,6 @@ { "type": "object", - "description": "An object representing a Server.", + "description": "An object representing a message broker, a server or any other kind of computer program capable of sending and/or receiving data", "required": [ "url", "protocol" @@ -13,38 +13,48 @@ }, "properties": { "url": { - "type": "string" + "type": "string", + "description": "A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the AsyncAPI document is being served." }, "description": { - "type": "string" + "type": "string", + "description": "An optional string describing the host designated by the URL. CommonMark syntax MAY be used for rich text representation." }, "protocol": { "type": "string", - "description": "The transfer protocol." + "description": "The protocol this URL supports for connection. Supported protocol include, but are not limited to: amqp, amqps, http, https, ibmmq, jms, kafka, kafka-secure, anypointmq, mqtt, secure-mqtt, solace, stomp, stomps, ws, wss, mercure, googlepubsub." }, "protocolVersion": { - "type": "string" + "type": "string", + "description": "The version of the protocol used for connection. For instance: AMQP 0.9.1, HTTP 2.0, Kafka 1.0.0, etc." }, "variables": { + "description": "A map between a variable name and its value. The value is used for substitution in the server's URL template.", "$ref": "http://asyncapi.com/definitions/2.6.0/serverVariables.json" }, "security": { "type": "array", + "description": "A declaration of which security mechanisms can be used with this server. The list of values includes alternative security requirement objects that can be used. ", "items": { "$ref": "http://asyncapi.com/definitions/2.6.0/SecurityRequirement.json" } }, "bindings": { + "description": "A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the server.", "$ref": "http://asyncapi.com/definitions/2.6.0/bindingsObject.json" }, "tags": { "type": "array", + "description": "A list of tags for logical grouping and categorization of servers.", "items": { "$ref": "http://asyncapi.com/definitions/2.6.0/tag.json" }, "uniqueItems": true } }, + "example": { + "$ref": "http://asyncapi.com/examples/2.6.0/server.json" + }, "$schema": "http://json-schema.org/draft-07/schema#", "$id": "http://asyncapi.com/definitions/2.6.0/server.json" } \ No newline at end of file diff --git a/definitions/2.6.0/serverVariable.json b/definitions/2.6.0/serverVariable.json index b12f425f..831e80cd 100644 --- a/definitions/2.6.0/serverVariable.json +++ b/definitions/2.6.0/serverVariable.json @@ -10,19 +10,23 @@ "properties": { "enum": { "type": "array", + "description": "An enumeration of string values to be used if the substitution options are from a limited set.", "items": { "type": "string" }, "uniqueItems": true }, "default": { - "type": "string" + "type": "string", + "description": "The default value to use for substitution, and to send, if an alternate value is not supplied." }, "description": { - "type": "string" + "type": "string", + "description": "An optional description for the server variable. " }, "examples": { "type": "array", + "description": "An array of examples of the server variable.", "items": { "type": "string" } diff --git a/definitions/2.6.0/serverVariables.json b/definitions/2.6.0/serverVariables.json index 23787ac4..bfc838c5 100644 --- a/definitions/2.6.0/serverVariables.json +++ b/definitions/2.6.0/serverVariables.json @@ -1,5 +1,6 @@ { "type": "object", + "description": "A map between a variable name and its value. The value is used for substitution in the server's URL template.", "additionalProperties": { "oneOf": [ { diff --git a/definitions/2.6.0/servers.json b/definitions/2.6.0/servers.json index 237eb0f7..a07f6a61 100644 --- a/definitions/2.6.0/servers.json +++ b/definitions/2.6.0/servers.json @@ -1,5 +1,5 @@ { - "description": "An object representing multiple servers.", + "description": "The Servers Object is a map of Server Objects.", "type": "object", "additionalProperties": { "oneOf": [ @@ -11,6 +11,9 @@ } ] }, + "example": { + "$ref": "http://asyncapi.com/examples/2.6.0/servers.json" + }, "$schema": "http://json-schema.org/draft-07/schema#", "$id": "http://asyncapi.com/definitions/2.6.0/servers.json" } \ No newline at end of file diff --git a/definitions/2.6.0/symmetricEncryption.json b/definitions/2.6.0/symmetricEncryption.json index 5981dc78..b643421f 100644 --- a/definitions/2.6.0/symmetricEncryption.json +++ b/definitions/2.6.0/symmetricEncryption.json @@ -6,12 +6,14 @@ "properties": { "type": { "type": "string", + "description": "The type of the security scheme.", "enum": [ "symmetricEncryption" ] }, "description": { - "type": "string" + "type": "string", + "description": "A short description for security scheme." } }, "patternProperties": { @@ -19,6 +21,9 @@ "$ref": "http://asyncapi.com/definitions/2.6.0/specificationExtension.json" } }, + "example": { + "$ref": "http://asyncapi.com/examples/2.6.0/symmetricEncryption.json" + }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#", "$id": "http://asyncapi.com/definitions/2.6.0/symmetricEncryption.json" diff --git a/definitions/2.6.0/tag.json b/definitions/2.6.0/tag.json index 2e0a28ad..a4c9fe1e 100644 --- a/definitions/2.6.0/tag.json +++ b/definitions/2.6.0/tag.json @@ -1,17 +1,21 @@ { "type": "object", + "description": "Allows adding meta data to a single tag.", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { - "type": "string" + "type": "string", + "description": "The name of the tag." }, "description": { - "type": "string" + "type": "string", + "description": "A short description for the tag." }, "externalDocs": { + "description": "Additional external documentation for this tag.", "$ref": "http://asyncapi.com/definitions/2.6.0/externalDocs.json" } }, @@ -20,6 +24,9 @@ "$ref": "http://asyncapi.com/definitions/2.6.0/specificationExtension.json" } }, + "example": { + "$ref": "http://asyncapi.com/examples/2.6.0/tag.json" + }, "$schema": "http://json-schema.org/draft-07/schema#", "$id": "http://asyncapi.com/definitions/2.6.0/tag.json" } \ No newline at end of file diff --git a/definitions/2.6.0/userPassword.json b/definitions/2.6.0/userPassword.json index 8f1e7a41..3c9a5f90 100644 --- a/definitions/2.6.0/userPassword.json +++ b/definitions/2.6.0/userPassword.json @@ -6,12 +6,14 @@ "properties": { "type": { "type": "string", + "description": "The type of the security scheme. ", "enum": [ "userPassword" ] }, "description": { - "type": "string" + "type": "string", + "description": "A short description for security scheme." } }, "patternProperties": { @@ -19,6 +21,9 @@ "$ref": "http://asyncapi.com/definitions/2.6.0/specificationExtension.json" } }, + "example": { + "$ref": "http://asyncapi.com/examples/2.6.0/userPassword.json" + }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#", "$id": "http://asyncapi.com/definitions/2.6.0/userPassword.json" diff --git a/examples/2.6.0/APIKeyHTTPSecurityScheme.json b/examples/2.6.0/APIKeyHTTPSecurityScheme.json new file mode 100644 index 00000000..e1bddc93 --- /dev/null +++ b/examples/2.6.0/APIKeyHTTPSecurityScheme.json @@ -0,0 +1,7 @@ +[ + { + "type": "httpApiKey", + "name": "api_key", + "in": "header" + } +] \ No newline at end of file diff --git a/examples/2.6.0/BearerHTTPSecurityScheme.json b/examples/2.6.0/BearerHTTPSecurityScheme.json new file mode 100644 index 00000000..adb233f7 --- /dev/null +++ b/examples/2.6.0/BearerHTTPSecurityScheme.json @@ -0,0 +1,7 @@ +[ + { + "type": "http", + "scheme": "bearer", + "bearerFormat": "JWT" + } +] \ No newline at end of file diff --git a/examples/2.6.0/ReferenceObject.json b/examples/2.6.0/ReferenceObject.json new file mode 100644 index 00000000..9a5e20bb --- /dev/null +++ b/examples/2.6.0/ReferenceObject.json @@ -0,0 +1,5 @@ +[ + { + "$ref": "#/components/schemas/Pet" + } +] \ No newline at end of file diff --git a/examples/2.6.0/Sasl.json b/examples/2.6.0/Sasl.json new file mode 100644 index 00000000..85ea380b --- /dev/null +++ b/examples/2.6.0/Sasl.json @@ -0,0 +1,5 @@ +[ + { + "type": "scramSha512" + } +] \ No newline at end of file diff --git a/examples/2.6.0/SecurityRequirement.json b/examples/2.6.0/SecurityRequirement.json new file mode 100644 index 00000000..7bb520a6 --- /dev/null +++ b/examples/2.6.0/SecurityRequirement.json @@ -0,0 +1,5 @@ +[ + { + "petstore_auth": ["write:pets", "read:pets"] + } +] \ No newline at end of file diff --git a/examples/2.6.0/SecurityScheme.json b/examples/2.6.0/SecurityScheme.json new file mode 100644 index 00000000..eb52bb8b --- /dev/null +++ b/examples/2.6.0/SecurityScheme.json @@ -0,0 +1,5 @@ +[ + { + "type": "userPassword" + } +] \ No newline at end of file diff --git a/examples/2.6.0/X509.json b/examples/2.6.0/X509.json new file mode 100644 index 00000000..690ba0a2 --- /dev/null +++ b/examples/2.6.0/X509.json @@ -0,0 +1,5 @@ +[ + { + "type": "X509" + } +] \ No newline at end of file diff --git a/examples/2.6.0/apiKey.json b/examples/2.6.0/apiKey.json new file mode 100644 index 00000000..777b966d --- /dev/null +++ b/examples/2.6.0/apiKey.json @@ -0,0 +1,6 @@ +[ + { + "type": "apiKey", + "in": "user" + } +] \ No newline at end of file diff --git a/examples/2.6.0/channelItem.json b/examples/2.6.0/channelItem.json new file mode 100644 index 00000000..fdf7a6fb --- /dev/null +++ b/examples/2.6.0/channelItem.json @@ -0,0 +1,54 @@ +[ + { + "description": "This channel is used to exchange messages about users signing up", + "subscribe": { + "summary": "A user signed up.", + "message": { + "description": "A longer description of the message", + "payload": { + "type": "object", + "properties": { + "user": { + "$ref": "#/components/schemas/user" + }, + "signup": { + "$ref": "#/components/schemas/signup" + } + } + } + } + }, + "bindings": { + "amqp": { + "is": "queue", + "queue": { + "exclusive": true + } + } + } + }, + { + "subscribe": { + "message": { + "oneOf": [ + { "$ref": "#/components/messages/signup" }, + { "$ref": "#/components/messages/login" } + ] + } + } + }, + { + "description": "This application publishes WebUICommand messages to an AMQP queue on RabbitMQ brokers in the Staging and Production environments.", + "servers": ["rabbitmqBrokerInProd", "rabbitmqBrokerInStaging"], + "subscribe": { + "message": { + "$ref": "#/components/messages/WebUICommand" + } + }, + "bindings": { + "amqp": { + "is": "queue" + } + } + } +] \ No newline at end of file diff --git a/examples/2.6.0/channels.json b/examples/2.6.0/channels.json new file mode 100644 index 00000000..b538aa99 --- /dev/null +++ b/examples/2.6.0/channels.json @@ -0,0 +1,11 @@ +[ + { + "user/signedup": { + "subscribe": { + "message": { + "$ref": "#/components/messages/userSignedUp" + } + } + } + } +] \ No newline at end of file diff --git a/examples/2.6.0/components.json b/examples/2.6.0/components.json new file mode 100644 index 00000000..71734aed --- /dev/null +++ b/examples/2.6.0/components.json @@ -0,0 +1,131 @@ +[ + { + "components": { + "schemas": { + "Category": { + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64" + }, + "name": { + "type": "string" + } + } + }, + "Tag": { + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64" + }, + "name": { + "type": "string" + } + } + } + }, + "servers": { + "development": { + "url": "{stage}.gigantic-server.com:{port}", + "description": "Development server", + "protocol": "amqp", + "protocolVersion": "0.9.1", + "variables": { + "stage": { + "$ref": "#/components/serverVariables/stage" + }, + "port": { + "$ref": "#/components/serverVariables/port" + } + } + } + }, + "serverVariables": { + "stage": { + "default": "demo", + "description": "This value is assigned by the service provider, in this example `gigantic-server.com`" + }, + "port": { + "enum": ["8883", "8884"], + "default": "8883" + } + }, + "channels": { + "user/signedup": { + "subscribe": { + "message": { + "$ref": "#/components/messages/userSignUp" + } + } + } + }, + "messages": { + "userSignUp": { + "summary": "Action to sign a user up.", + "description": "Multiline description of what this action does.\nHere you have another line.\n", + "tags": [ + { + "name": "user" + }, + { + "name": "signup" + } + ], + "headers": { + "type": "object", + "properties": { + "applicationInstanceId": { + "description": "Unique identifier for a given instance of the publishing application", + "type": "string" + } + } + }, + "payload": { + "type": "object", + "properties": { + "user": { + "$ref": "#/components/schemas/userCreate" + }, + "signup": { + "$ref": "#/components/schemas/signup" + } + } + } + } + }, + "parameters": { + "userId": { + "description": "Id of the user.", + "schema": { + "type": "string" + } + } + }, + "correlationIds": { + "default": { + "description": "Default Correlation ID", + "location": "$message.header#/correlationId" + } + }, + "messageTraits": { + "commonHeaders": { + "headers": { + "type": "object", + "properties": { + "my-app-header": { + "type": "integer", + "minimum": 0, + "maximum": 100 + } + } + } + } + } + } + } + + +] \ No newline at end of file diff --git a/examples/2.6.0/contact.json b/examples/2.6.0/contact.json new file mode 100644 index 00000000..1c81a963 --- /dev/null +++ b/examples/2.6.0/contact.json @@ -0,0 +1,8 @@ +[ + { + "name": "API Support", + "url": "https://www.example.com/support", + "email": "support@example.com" + } + +] \ No newline at end of file diff --git a/examples/2.6.0/correlationId.json b/examples/2.6.0/correlationId.json new file mode 100644 index 00000000..c4946700 --- /dev/null +++ b/examples/2.6.0/correlationId.json @@ -0,0 +1,6 @@ +[ + { + "description": "Default Correlation ID", + "location": "$message.header#/correlationId" + } +] \ No newline at end of file diff --git a/examples/2.6.0/externalDocs.json b/examples/2.6.0/externalDocs.json new file mode 100644 index 00000000..242032c6 --- /dev/null +++ b/examples/2.6.0/externalDocs.json @@ -0,0 +1,6 @@ +[ + { + "description": "Find more info here", + "url": "https://example.com" + } +] diff --git a/examples/2.6.0/info.json b/examples/2.6.0/info.json new file mode 100644 index 00000000..ef43152d --- /dev/null +++ b/examples/2.6.0/info.json @@ -0,0 +1,16 @@ +[ + { + "title": "AsyncAPI Sample App", + "description": "This is a sample server.", + "termsOfService": "https://asyncapi.org/terms/", + "contact": { + "name": "API Support", + "url": "https://www.example.com/support", + "email": "support@example.com" + }, + "license": { + "name": "Apache 2.0", + "url": "https://www.apache.org/licenses/LICENSE-2.0.html" + } + } +] \ No newline at end of file diff --git a/examples/2.6.0/license.json b/examples/2.6.0/license.json new file mode 100644 index 00000000..18becf4f --- /dev/null +++ b/examples/2.6.0/license.json @@ -0,0 +1,7 @@ +[ + { + "name": "Apache 2.0", + "url": "https://www.apache.org/licenses/LICENSE-2.0.html" + } + +] \ No newline at end of file diff --git a/examples/2.6.0/message.json b/examples/2.6.0/message.json new file mode 100644 index 00000000..f6b7f0b4 --- /dev/null +++ b/examples/2.6.0/message.json @@ -0,0 +1,78 @@ +[ + { + "messageId": "userSignup", + "name": "UserSignup", + "title": "User signup", + "summary": "Action to sign a user up.", + "description": "A longer description", + "contentType": "application/json", + "tags": [ + { "name": "user" }, + { "name": "signup" }, + { "name": "register" } + ], + "headers": { + "type": "object", + "properties": { + "correlationId": { + "description": "Correlation ID set by application", + "type": "string" + }, + "applicationInstanceId": { + "description": "Unique identifier for a given instance of the publishing application", + "type": "string" + } + } + }, + "payload": { + "type": "object", + "properties": { + "user": { + "$ref": "#/components/schemas/userCreate" + }, + "signup": { + "$ref": "#/components/schemas/signup" + } + } + }, + "correlationId": { + "description": "Default Correlation ID", + "location": "$message.header#/correlationId" + }, + "traits": [{ "$ref": "#/components/messageTraits/commonHeaders" }], + "examples": [ + { + "name": "SimpleSignup", + "summary": "A simple UserSignup example message", + "headers": { + "correlationId": "my-correlation-id", + "applicationInstanceId": "myInstanceId" + }, + "payload": { + "user": { + "someUserKey": "someUserValue" + }, + "signup": { + "someSignupKey": "someSignupValue" + } + } + } + ] + }, + { + "messageId": "userSignup", + "name": "UserSignup", + "title": "User signup", + "summary": "Action to sign a user up.", + "description": "A longer description", + "tags": [ + { "name": "user" }, + { "name": "signup" }, + { "name": "register" } + ], + "schemaFormat": "application/vnd.apache.avro+json;version=1.9.0", + "payload": { + "$ref": "path/to/user-create.avsc#/UserCreate" + } + } +] \ No newline at end of file diff --git a/examples/2.6.0/messageTrait.json b/examples/2.6.0/messageTrait.json new file mode 100644 index 00000000..e1d5a26b --- /dev/null +++ b/examples/2.6.0/messageTrait.json @@ -0,0 +1,6 @@ +[ + { + "schemaFormat": "application/vnd.apache.avro+json;version=1.9.0", + "contentType": "application/json" + } +] \ No newline at end of file diff --git a/examples/2.6.0/oauth2Flow.json b/examples/2.6.0/oauth2Flow.json new file mode 100644 index 00000000..d299f719 --- /dev/null +++ b/examples/2.6.0/oauth2Flow.json @@ -0,0 +1,22 @@ +[ + { + "type": "oauth2", + "flows": { + "implicit": { + "authorizationUrl": "https://example.com/api/oauth/dialog", + "scopes": { + "write:pets": "modify pets in your account", + "read:pets": "read your pets" + } + }, + "authorizationCode": { + "authorizationUrl": "https://example.com/api/oauth/dialog", + "tokenUrl": "https://example.com/api/oauth/token", + "scopes": { + "write:pets": "modify pets in your account", + "read:pets": "read your pets" + } + } + } + } +] \ No newline at end of file diff --git a/examples/2.6.0/operation.json b/examples/2.6.0/operation.json new file mode 100644 index 00000000..38a1a9f1 --- /dev/null +++ b/examples/2.6.0/operation.json @@ -0,0 +1,45 @@ +[ + { + "operationId": "registerUser", + "summary": "Action to sign a user up.", + "description": "A longer description", + "security": [ + { + "petstore_auth": ["write:pets", "read:pets"] + } + ], + "tags": [ + { "name": "user" }, + { "name": "signup" }, + { "name": "register" } + ], + "message": { + "headers": { + "type": "object", + "properties": { + "applicationInstanceId": { + "description": "Unique identifier for a given instance of the publishing application", + "type": "string" + } + } + }, + "payload": { + "type": "object", + "properties": { + "user": { + "$ref": "#/components/schemas/userCreate" + }, + "signup": { + "$ref": "#/components/schemas/signup" + } + } + } + }, + "bindings": { + "amqp": { + "ack": false + } + }, + "traits": [{ "$ref": "#/components/operationTraits/kafka" }] + } +] \ No newline at end of file diff --git a/examples/2.6.0/operationTrait.json b/examples/2.6.0/operationTrait.json new file mode 100644 index 00000000..b6210352 --- /dev/null +++ b/examples/2.6.0/operationTrait.json @@ -0,0 +1,9 @@ +[ + { + "bindings": { + "amqp": { + "ack": false + } + } + } +] diff --git a/examples/2.6.0/parameter.json b/examples/2.6.0/parameter.json new file mode 100644 index 00000000..198cc155 --- /dev/null +++ b/examples/2.6.0/parameter.json @@ -0,0 +1,20 @@ +[ + { + "user/{userId}/signup": { + "parameters": { + "userId": { + "description": "Id of the user.", + "schema": { + "type": "string" + }, + "location": "$message.payload#/user/id" + } + }, + "subscribe": { + "message": { + "$ref": "#/components/messages/userSignedUp" + } + } + } + } +] \ No newline at end of file diff --git a/examples/2.6.0/parameters.json b/examples/2.6.0/parameters.json new file mode 100644 index 00000000..02307853 --- /dev/null +++ b/examples/2.6.0/parameters.json @@ -0,0 +1,19 @@ +[ + { + "user/{userId}/signup": { + "parameters": { + "userId": { + "description": "Id of the user.", + "schema": { + "type": "string" + } + } + }, + "subscribe": { + "message": { + "$ref": "#/components/messages/userSignedUp" + } + } + } + } +] \ No newline at end of file diff --git a/examples/2.6.0/schema.json b/examples/2.6.0/schema.json new file mode 100644 index 00000000..78fa52ae --- /dev/null +++ b/examples/2.6.0/schema.json @@ -0,0 +1,23 @@ +[ + { + "type": "string", + "format": "email" + }, + { + "type": "object", + "required": ["name"], + "properties": { + "name": { + "type": "string" + }, + "address": { + "$ref": "#/components/schemas/Address" + }, + "age": { + "type": "integer", + "format": "int32", + "minimum": 0 + } + } + } +] \ No newline at end of file diff --git a/examples/2.6.0/server.json b/examples/2.6.0/server.json new file mode 100644 index 00000000..97e213f8 --- /dev/null +++ b/examples/2.6.0/server.json @@ -0,0 +1,8 @@ +[ + { + "url": "development.gigantic-server.com", + "description": "Development server", + "protocol": "kafka", + "protocolVersion": "1.0.0" + } +] \ No newline at end of file diff --git a/examples/2.6.0/servers.json b/examples/2.6.0/servers.json new file mode 100644 index 00000000..4554023a --- /dev/null +++ b/examples/2.6.0/servers.json @@ -0,0 +1,41 @@ +[ + { + "development": { + "url": "development.gigantic-server.com", + "description": "Development server", + "protocol": "amqp", + "protocolVersion": "0.9.1", + "tags": [ + { + "name": "env:development", + "description": "This environment is meant for developers to run their own tests" + } + ] + }, + "staging": { + "url": "staging.gigantic-server.com", + "description": "Staging server", + "protocol": "amqp", + "protocolVersion": "0.9.1", + "tags": [ + { + "name": "env:staging", + "description": "This environment is a replica of the production environment" + } + ] + }, + "production": { + "url": "api.gigantic-server.com", + "description": "Production server", + "protocol": "amqp", + "protocolVersion": "0.9.1", + "tags": [ + { + "name": "env:production", + "description": "This environment is the live environment available for final users" + } + ] + } + } + +] \ No newline at end of file diff --git a/examples/2.6.0/symmetricEncryption.json b/examples/2.6.0/symmetricEncryption.json new file mode 100644 index 00000000..dc0f0a84 --- /dev/null +++ b/examples/2.6.0/symmetricEncryption.json @@ -0,0 +1,5 @@ +[ + { + "type": "symmetricEncryption" + } +] \ No newline at end of file diff --git a/examples/2.6.0/tag.json b/examples/2.6.0/tag.json new file mode 100644 index 00000000..69b7e642 --- /dev/null +++ b/examples/2.6.0/tag.json @@ -0,0 +1,6 @@ +[ + { + "name": "user", + "description": "User-related messages" + } +] \ No newline at end of file diff --git a/examples/2.6.0/userPassword.json b/examples/2.6.0/userPassword.json new file mode 100644 index 00000000..eb52bb8b --- /dev/null +++ b/examples/2.6.0/userPassword.json @@ -0,0 +1,5 @@ +[ + { + "type": "userPassword" + } +] \ No newline at end of file diff --git a/schemas/2.6.0-without-$id.json b/schemas/2.6.0-without-$id.json index a83ea308..1c62ed27 100644 --- a/schemas/2.6.0-without-$id.json +++ b/schemas/2.6.0-without-$id.json @@ -60,7 +60,7 @@ }, "info": { "type": "object", - "description": "General information about the API.", + "description": "The object provides metadata about the API. The metadata can be used by the clients if needed.", "required": [ "version", "title" @@ -95,11 +95,27 @@ "license": { "$ref": "#/definitions/license" } - } + }, + "examples": [ + { + "title": "AsyncAPI Sample App", + "description": "This is a sample server.", + "termsOfService": "https://asyncapi.org/terms/", + "contact": { + "name": "API Support", + "url": "https://www.example.com/support", + "email": "support@example.com" + }, + "license": { + "name": "Apache 2.0", + "url": "https://www.apache.org/licenses/LICENSE-2.0.html" + } + } + ] }, "contact": { "type": "object", - "description": "Contact information for the owners of the API.", + "description": "Contact information for the exposed API.", "additionalProperties": false, "properties": { "name": { @@ -121,7 +137,14 @@ "^x-[\\w\\d\\.\\x2d_]+$": { "$ref": "#/definitions/specificationExtension" } - } + }, + "examples": [ + { + "name": "API Support", + "url": "https://www.example.com/support", + "email": "support@example.com" + } + ] }, "license": { "type": "object", @@ -144,7 +167,13 @@ "^x-[\\w\\d\\.\\x2d_]+$": { "$ref": "#/definitions/specificationExtension" } - } + }, + "examples": [ + { + "name": "Apache 2.0", + "url": "https://www.apache.org/licenses/LICENSE-2.0.html" + } + ] }, "servers": { "description": "An object representing multiple servers.", @@ -158,7 +187,47 @@ "$ref": "#/definitions/server" } ] - } + }, + "examples": [ + { + "development": { + "url": "development.gigantic-server.com", + "description": "Development server", + "protocol": "amqp", + "protocolVersion": "0.9.1", + "tags": [ + { + "name": "env:development", + "description": "This environment is meant for developers to run their own tests" + } + ] + }, + "staging": { + "url": "staging.gigantic-server.com", + "description": "Staging server", + "protocol": "amqp", + "protocolVersion": "0.9.1", + "tags": [ + { + "name": "env:staging", + "description": "This environment is a replica of the production environment" + } + ] + }, + "production": { + "url": "api.gigantic-server.com", + "description": "Production server", + "protocol": "amqp", + "protocolVersion": "0.9.1", + "tags": [ + { + "name": "env:production", + "description": "This environment is the live environment available for final users" + } + ] + } + } + ] }, "Reference": { "type": "object", @@ -173,11 +242,17 @@ }, "ReferenceObject": { "type": "string", - "format": "uri-reference" + "description": "A simple object to allow referencing other components in the specification, internally and externally.", + "format": "uri-reference", + "examples": [ + { + "$ref": "#/components/schemas/Pet" + } + ] }, "server": { "type": "object", - "description": "An object representing a Server.", + "description": "An object representing a message broker, a server or any other kind of computer program capable of sending and/or receiving data", "required": [ "url", "protocol" @@ -190,41 +265,57 @@ }, "properties": { "url": { - "type": "string" + "type": "string", + "description": "A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the AsyncAPI document is being served." }, "description": { - "type": "string" + "type": "string", + "description": "An optional string describing the host designated by the URL. CommonMark syntax MAY be used for rich text representation." }, "protocol": { "type": "string", - "description": "The transfer protocol." + "description": "The protocol this URL supports for connection. Supported protocol include, but are not limited to: amqp, amqps, http, https, ibmmq, jms, kafka, kafka-secure, anypointmq, mqtt, secure-mqtt, solace, stomp, stomps, ws, wss, mercure, googlepubsub." }, "protocolVersion": { - "type": "string" + "type": "string", + "description": "The version of the protocol used for connection. For instance: AMQP 0.9.1, HTTP 2.0, Kafka 1.0.0, etc." }, "variables": { + "description": "A map between a variable name and its value. The value is used for substitution in the server's URL template.", "$ref": "#/definitions/serverVariables" }, "security": { "type": "array", + "description": "A declaration of which security mechanisms can be used with this server. The list of values includes alternative security requirement objects that can be used. ", "items": { "$ref": "#/definitions/SecurityRequirement" } }, "bindings": { + "description": "A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the server.", "$ref": "#/definitions/bindingsObject" }, "tags": { "type": "array", + "description": "A list of tags for logical grouping and categorization of servers.", "items": { "$ref": "#/definitions/tag" }, "uniqueItems": true } - } + }, + "examples": [ + { + "url": "development.gigantic-server.com", + "description": "Development server", + "protocol": "kafka", + "protocolVersion": "1.0.0" + } + ] }, "serverVariables": { "type": "object", + "description": "A map between a variable name and its value. The value is used for substitution in the server's URL template.", "additionalProperties": { "oneOf": [ { @@ -248,19 +339,23 @@ "properties": { "enum": { "type": "array", + "description": "An enumeration of string values to be used if the substitution options are from a limited set.", "items": { "type": "string" }, "uniqueItems": true }, "default": { - "type": "string" + "type": "string", + "description": "The default value to use for substitution, and to send, if an alternate value is not supplied." }, "description": { - "type": "string" + "type": "string", + "description": "An optional description for the server variable. " }, "examples": { "type": "array", + "description": "An array of examples of the server variable.", "items": { "type": "string" } @@ -269,16 +364,26 @@ }, "SecurityRequirement": { "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 - } + }, + "examples": [ + { + "petstore_auth": [ + "write:pets", + "read:pets" + ] + } + ] }, "bindingsObject": { "type": "object", + "description": "Map describing protocol-specific definitions for a server.", "additionalProperties": true, "properties": { "http": {}, @@ -303,18 +408,22 @@ }, "tag": { "type": "object", + "description": "Allows adding meta data to a single tag.", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { - "type": "string" + "type": "string", + "description": "The name of the tag." }, "description": { - "type": "string" + "type": "string", + "description": "A short description for the tag." }, "externalDocs": { + "description": "Additional external documentation for this tag.", "$ref": "#/definitions/externalDocs" } }, @@ -322,32 +431,47 @@ "^x-[\\w\\d\\.\\x2d_]+$": { "$ref": "#/definitions/specificationExtension" } - } + }, + "examples": [ + { + "name": "user", + "description": "User-related messages" + } + ] }, "externalDocs": { "type": "object", "additionalProperties": false, - "description": "information about external documentation", + "description": "Allows referencing an external resource for extended documentation.", "required": [ "url" ], "properties": { "description": { - "type": "string" + "type": "string", + "description": "A short description of the target documentation." }, "url": { "type": "string", - "format": "uri" + "format": "uri", + "description": "The URL for the target documentation. This MUST be in the form of an absolute URL." } }, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { "$ref": "#/definitions/specificationExtension" } - } + }, + "examples": [ + { + "description": "Find more info here", + "url": "https://example.com" + } + ] }, "channels": { "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", @@ -355,10 +479,22 @@ }, "additionalProperties": { "$ref": "#/definitions/channelItem" - } + }, + "examples": [ + { + "user/signedup": { + "subscribe": { + "message": { + "$ref": "#/components/messages/userSignedUp" + } + } + } + } + ] }, "channelItem": { "type": "object", + "description": "Describes the operations available on a single channel.", "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { @@ -397,10 +533,72 @@ "bindings": { "$ref": "#/definitions/bindingsObject" } - } + }, + "examples": [ + { + "description": "This channel is used to exchange messages about users signing up", + "subscribe": { + "summary": "A user signed up.", + "message": { + "description": "A longer description of the message", + "payload": { + "type": "object", + "properties": { + "user": { + "$ref": "#/components/schemas/user" + }, + "signup": { + "$ref": "#/components/schemas/signup" + } + } + } + } + }, + "bindings": { + "amqp": { + "is": "queue", + "queue": { + "exclusive": true + } + } + } + }, + { + "subscribe": { + "message": { + "oneOf": [ + { + "$ref": "#/components/messages/signup" + }, + { + "$ref": "#/components/messages/login" + } + ] + } + } + }, + { + "description": "This application publishes WebUICommand messages to an AMQP queue on RabbitMQ brokers in the Staging and Production environments.", + "servers": [ + "rabbitmqBrokerInProd", + "rabbitmqBrokerInStaging" + ], + "subscribe": { + "message": { + "$ref": "#/components/messages/WebUICommand" + } + }, + "bindings": { + "amqp": { + "is": "queue" + } + } + } + ] }, "parameters": { "type": "object", + "description": "JSON objects describing re-usable channel parameters.", "additionalProperties": { "oneOf": [ { @@ -411,9 +609,28 @@ } ] }, - "description": "JSON objects describing re-usable channel parameters." + "examples": [ + { + "user/{userId}/signup": { + "parameters": { + "userId": { + "description": "Id of the user.", + "schema": { + "type": "string" + } + } + }, + "subscribe": { + "message": { + "$ref": "#/components/messages/userSignedUp" + } + } + } + } + ] }, "parameter": { + "description": "Describes a parameter included in a channel name.", "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { @@ -433,9 +650,30 @@ "description": "A runtime expression that specifies the location of the parameter value", "pattern": "^\\$message\\.(header|payload)#(\\/(([^\\/~])|(~[01]))*)*" } - } + }, + "examples": [ + { + "user/{userId}/signup": { + "parameters": { + "userId": { + "description": "Id of the user.", + "schema": { + "type": "string" + }, + "location": "$message.payload#/user/id" + } + }, + "subscribe": { + "message": { + "$ref": "#/components/messages/userSignedUp" + } + } + } + } + ] }, "schema": { + "description": "The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays.", "allOf": [ { "$ref": "#/definitions/json-schema-draft-07-schema" @@ -518,14 +756,42 @@ "$ref": "#/definitions/schema" }, "discriminator": { - "type": "string" + "type": "string", + "description": "Adds support for polymorphism. The discriminator is the schema property name that is used to differentiate between other schema that inherit this schema. " }, "externalDocs": { + "description": "Additional external documentation for this schema.", "$ref": "#/definitions/externalDocs" }, "deprecated": { "type": "boolean", - "default": false + "default": false, + "description": "Specifies that a schema is deprecated and SHOULD be transitioned out of usage" + } + } + } + ], + "examples": [ + { + "type": "string", + "format": "email" + }, + { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string" + }, + "address": { + "$ref": "#/components/schemas/Address" + }, + "age": { + "type": "integer", + "format": "int32", + "minimum": 0 } } } @@ -776,6 +1042,7 @@ }, "operation": { "type": "object", + "description": "Describes a publish or a subscribe operation. This provides a place to document how and why messages are sent and received.", "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { @@ -785,6 +1052,7 @@ "properties": { "traits": { "type": "array", + "description": "A list of traits to apply to the operation object.", "items": { "oneOf": [ { @@ -797,19 +1065,23 @@ } }, "summary": { - "type": "string" + "type": "string", + "description": "A short summary of what the operation is about." }, "description": { - "type": "string" + "type": "string", + "description": "A verbose explanation of the operation." }, "security": { "type": "array", + "description": "A declaration of which security mechanisms are associated with this operation.", "items": { "$ref": "#/definitions/SecurityRequirement" } }, "tags": { "type": "array", + "description": "A list of tags for logical grouping and categorization of operations.", "items": { "$ref": "#/definitions/tag" }, @@ -827,10 +1099,22 @@ "message": { "$ref": "#/definitions/message" } - } + }, + "examples": [ + { + "user/signedup": { + "subscribe": { + "message": { + "$ref": "#/components/messages/userSignedUp" + } + } + } + } + ] }, "operationTrait": { "type": "object", + "description": "Describes a trait that MAY be applied to an Operation Object.", "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { @@ -839,13 +1123,16 @@ }, "properties": { "summary": { - "type": "string" + "type": "string", + "description": "A short summary of what the operation is about." }, "description": { - "type": "string" + "type": "string", + "description": "A verbose explanation of the operation." }, "tags": { "type": "array", + "description": "A list of tags for logical grouping and categorization of operations.", "items": { "$ref": "#/definitions/tag" }, @@ -855,10 +1142,12 @@ "$ref": "#/definitions/externalDocs" }, "operationId": { - "type": "string" + "type": "string", + "description": "Unique string used to identify the operation. The id MUST be unique among all operations described in the API." }, "security": { "type": "array", + "description": "A declaration of which security mechanisms are associated with this operation. ", "items": { "$ref": "#/definitions/SecurityRequirement" } @@ -866,7 +1155,16 @@ "bindings": { "$ref": "#/definitions/bindingsObject" } - } + }, + "examples": [ + { + "bindings": { + "amqp": { + "ack": false + } + } + } + ] }, "message": { "oneOf": [ @@ -965,6 +1263,7 @@ }, "examples": { "type": "array", + "description": "List of examples.", "items": { "type": "object", "additionalProperties": false, @@ -990,9 +1289,12 @@ "description": "A brief summary of the message example." }, "headers": { - "type": "object" + "type": "object", + "description": "Schema definition of the application headers." }, - "payload": {} + "payload": { + "description": "Definition of the message payload. It can be of any type" + } } } }, @@ -1143,10 +1445,105 @@ } ] } + ], + "examples": [ + { + "messageId": "userSignup", + "name": "UserSignup", + "title": "User signup", + "summary": "Action to sign a user up.", + "description": "A longer description", + "contentType": "application/json", + "tags": [ + { + "name": "user" + }, + { + "name": "signup" + }, + { + "name": "register" + } + ], + "headers": { + "type": "object", + "properties": { + "correlationId": { + "description": "Correlation ID set by application", + "type": "string" + }, + "applicationInstanceId": { + "description": "Unique identifier for a given instance of the publishing application", + "type": "string" + } + } + }, + "payload": { + "type": "object", + "properties": { + "user": { + "$ref": "#/components/schemas/userCreate" + }, + "signup": { + "$ref": "#/components/schemas/signup" + } + } + }, + "correlationId": { + "description": "Default Correlation ID", + "location": "$message.header#/correlationId" + }, + "traits": [ + { + "$ref": "#/components/messageTraits/commonHeaders" + } + ], + "examples": [ + { + "name": "SimpleSignup", + "summary": "A simple UserSignup example message", + "headers": { + "correlationId": "my-correlation-id", + "applicationInstanceId": "myInstanceId" + }, + "payload": { + "user": { + "someUserKey": "someUserValue" + }, + "signup": { + "someSignupKey": "someSignupValue" + } + } + } + ] + }, + { + "messageId": "userSignup", + "name": "UserSignup", + "title": "User signup", + "summary": "Action to sign a user up.", + "description": "A longer description", + "tags": [ + { + "name": "user" + }, + { + "name": "signup" + }, + { + "name": "register" + } + ], + "schemaFormat": "application/vnd.apache.avro+json;version=1.9.0", + "payload": { + "$ref": "path/to/user-create.avsc#/UserCreate" + } + } ] }, "correlationId": { "type": "object", + "description": "An object that specifies an identifier at design time that can used for message tracing and correlation.", "required": [ "location" ], @@ -1166,10 +1563,17 @@ "description": "A runtime expression that specifies the location of the correlation ID", "pattern": "^\\$message\\.(header|payload)#(\\/(([^\\/~])|(~[01]))*)*" } - } + }, + "examples": [ + { + "description": "Default Correlation ID", + "location": "$message.header#/correlationId" + } + ] }, "messageTrait": { "type": "object", + "description": "Describes a trait that MAY be applied to a Message Object.", "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { @@ -1178,12 +1582,15 @@ }, "properties": { "schemaFormat": { - "type": "string" + "type": "string", + "description": "A string containing the name of the schema format/language used to define the message payload." }, "contentType": { - "type": "string" + "type": "string", + "description": "The content type to use when encoding/decoding a message's payload." }, "headers": { + "description": "Schema definition of the application headers.", "allOf": [ { "$ref": "#/definitions/schema" @@ -1198,9 +1605,11 @@ ] }, "messageId": { - "type": "string" + "type": "string", + "description": "Unique string used to identify the message. The id MUST be unique among all messages described in the API." }, "correlationId": { + "description": "Definition of the correlation ID used for message tracing or matching.", "oneOf": [ { "$ref": "#/definitions/Reference" @@ -1212,6 +1621,7 @@ }, "tags": { "type": "array", + "description": "A list of tags for logical grouping and categorization of messages.", "items": { "$ref": "#/definitions/tag" }, @@ -1242,14 +1652,51 @@ }, "examples": { "type": "array", + "description": "List of examples.", "items": { - "type": "object" + "type": "object", + "additionalProperties": false, + "anyOf": [ + { + "required": [ + "payload" + ] + }, + { + "required": [ + "headers" + ] + } + ], + "properties": { + "name": { + "type": "string", + "description": "Machine readable name of the message example." + }, + "summary": { + "type": "string", + "description": "A brief summary of the message example." + }, + "headers": { + "type": "object", + "description": "Schema definition of the application headers." + }, + "payload": { + "description": "Definition of the message payload. It can be of any type" + } + } } }, "bindings": { "$ref": "#/definitions/bindingsObject" } - } + }, + "examples": [ + { + "schemaFormat": "application/vnd.apache.avro+json;version=1.9.0", + "contentType": "application/json" + } + ] }, "openapiSchema_3_0": { "type": "object", @@ -1946,7 +2393,139 @@ "$ref": "#/definitions/bindingsObject" } } - } + }, + "examples": [ + { + "components": { + "schemas": { + "Category": { + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64" + }, + "name": { + "type": "string" + } + } + }, + "Tag": { + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64" + }, + "name": { + "type": "string" + } + } + } + }, + "servers": { + "development": { + "url": "{stage}.gigantic-server.com:{port}", + "description": "Development server", + "protocol": "amqp", + "protocolVersion": "0.9.1", + "variables": { + "stage": { + "$ref": "#/components/serverVariables/stage" + }, + "port": { + "$ref": "#/components/serverVariables/port" + } + } + } + }, + "serverVariables": { + "stage": { + "default": "demo", + "description": "This value is assigned by the service provider, in this example `gigantic-server.com`" + }, + "port": { + "enum": [ + "8883", + "8884" + ], + "default": "8883" + } + }, + "channels": { + "user/signedup": { + "subscribe": { + "message": { + "$ref": "#/components/messages/userSignUp" + } + } + } + }, + "messages": { + "userSignUp": { + "summary": "Action to sign a user up.", + "description": "Multiline description of what this action does.\nHere you have another line.\n", + "tags": [ + { + "name": "user" + }, + { + "name": "signup" + } + ], + "headers": { + "type": "object", + "properties": { + "applicationInstanceId": { + "description": "Unique identifier for a given instance of the publishing application", + "type": "string" + } + } + }, + "payload": { + "type": "object", + "properties": { + "user": { + "$ref": "#/components/schemas/userCreate" + }, + "signup": { + "$ref": "#/components/schemas/signup" + } + } + } + } + }, + "parameters": { + "userId": { + "description": "Id of the user.", + "schema": { + "type": "string" + } + } + }, + "correlationIds": { + "default": { + "description": "Default Correlation ID", + "location": "$message.header#/correlationId" + } + }, + "messageTraits": { + "commonHeaders": { + "headers": { + "type": "object", + "properties": { + "my-app-header": { + "type": "integer", + "minimum": 0, + "maximum": 100 + } + } + } + } + } + } + } + ] }, "schemas": { "type": "object", @@ -1963,6 +2542,7 @@ "description": "JSON objects describing the messages being consumed and produced by the API." }, "SecurityScheme": { + "description": "Defines a security scheme that can be used by the operations.", "oneOf": [ { "$ref": "#/definitions/userPassword" @@ -1991,6 +2571,11 @@ { "$ref": "#/definitions/SaslSecurityScheme" } + ], + "examples": [ + { + "type": "userPassword" + } ] }, "userPassword": { @@ -2001,12 +2586,14 @@ "properties": { "type": { "type": "string", + "description": "The type of the security scheme. ", "enum": [ "userPassword" ] }, "description": { - "type": "string" + "type": "string", + "description": "A short description for security scheme." } }, "patternProperties": { @@ -2014,7 +2601,12 @@ "$ref": "#/definitions/specificationExtension" } }, - "additionalProperties": false + "additionalProperties": false, + "examples": [ + { + "type": "userPassword" + } + ] }, "apiKey": { "type": "object", @@ -2025,19 +2617,22 @@ "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": { @@ -2045,7 +2640,13 @@ "$ref": "#/definitions/specificationExtension" } }, - "additionalProperties": false + "additionalProperties": false, + "examples": [ + { + "type": "apiKey", + "in": "user" + } + ] }, "X509": { "type": "object", @@ -2057,10 +2658,12 @@ "type": "string", "enum": [ "X509" - ] + ], + "description": "The type of the security scheme." }, "description": { - "type": "string" + "type": "string", + "description": "A short description for security scheme." } }, "patternProperties": { @@ -2068,7 +2671,12 @@ "$ref": "#/definitions/specificationExtension" } }, - "additionalProperties": false + "additionalProperties": false, + "examples": [ + { + "type": "X509" + } + ] }, "symmetricEncryption": { "type": "object", @@ -2078,12 +2686,14 @@ "properties": { "type": { "type": "string", + "description": "The type of the security scheme.", "enum": [ "symmetricEncryption" ] }, "description": { - "type": "string" + "type": "string", + "description": "A short description for security scheme." } }, "patternProperties": { @@ -2091,7 +2701,12 @@ "$ref": "#/definitions/specificationExtension" } }, - "additionalProperties": false + "additionalProperties": false, + "examples": [ + { + "type": "symmetricEncryption" + } + ] }, "asymmetricEncryption": { "type": "object", @@ -2101,12 +2716,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": { @@ -2135,6 +2752,7 @@ "properties": { "scheme": { "type": "string", + "description": "A short description for security scheme.", "enum": [ "bearer" ] @@ -2148,13 +2766,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" ] @@ -2176,21 +2797,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": { @@ -2210,15 +2835,18 @@ "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", @@ -2226,7 +2854,8 @@ ] }, "description": { - "type": "string" + "type": "string", + "description": "A short description for security scheme." } }, "patternProperties": { @@ -2234,10 +2863,18 @@ "$ref": "#/definitions/specificationExtension" } }, - "additionalProperties": false + "additionalProperties": false, + "examples": [ + { + "type": "httpApiKey", + "name": "api_key", + "in": "header" + } + ] }, "oauth2Flows": { "type": "object", + "description": "Allows configuration of the supported OAuth Flows.", "required": [ "type", "flows" @@ -2245,17 +2882,20 @@ "properties": { "type": { "type": "string", + "description": "A short description for security scheme.", "enum": [ "oauth2" ] }, "description": { - "type": "string" + "type": "string", + "description": "A short description for security scheme." }, "flows": { "type": "object", "properties": { "implicit": { + "description": "Configuration for the OAuth Implicit flow.", "allOf": [ { "$ref": "#/definitions/oauth2Flow" @@ -2276,6 +2916,7 @@ ] }, "password": { + "description": "Configuration for the OAuth Resource Owner Protected Credentials flow.", "allOf": [ { "$ref": "#/definitions/oauth2Flow" @@ -2296,6 +2937,7 @@ ] }, "clientCredentials": { + "description": "Configuration for the OAuth Client Credentials flow.", "allOf": [ { "$ref": "#/definitions/oauth2Flow" @@ -2316,6 +2958,7 @@ ] }, "authorizationCode": { + "description": "Configuration for the OAuth Authorization Code flow.", "allOf": [ { "$ref": "#/definitions/oauth2Flow" @@ -2341,20 +2984,25 @@ }, "oauth2Flow": { "type": "object", + "description": "Configuration details for a supported OAuth Flow", "properties": { "authorizationUrl": { "type": "string", - "format": "uri" + "format": "uri", + "description": "The authorization URL to be used for this flow. This MUST be in the form of an absolute URL." }, "tokenUrl": { "type": "string", - "format": "uri" + "format": "uri", + "description": "The token URL to be used for this flow. This MUST be in the form of an absolute URL." }, "refreshUrl": { "type": "string", - "format": "uri" + "format": "uri", + "description": "The URL to be used for obtaining refresh tokens. This MUST be in the form of an absolute URL." }, "scopes": { + "description": "The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it.", "$ref": "#/definitions/oauth2Scopes" } }, @@ -2363,7 +3011,29 @@ "$ref": "#/definitions/specificationExtension" } }, - "additionalProperties": false + "additionalProperties": false, + "examples": [ + { + "type": "oauth2", + "flows": { + "implicit": { + "authorizationUrl": "https://example.com/api/oauth/dialog", + "scopes": { + "write:pets": "modify pets in your account", + "read:pets": "read your pets" + } + }, + "authorizationCode": { + "authorizationUrl": "https://example.com/api/oauth/dialog", + "tokenUrl": "https://example.com/api/oauth/token", + "scopes": { + "write:pets": "modify pets in your account", + "read:pets": "read your pets" + } + } + } + } + ] }, "oauth2Scopes": { "type": "object", @@ -2420,12 +3090,14 @@ "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": { @@ -2433,7 +3105,12 @@ "$ref": "#/definitions/specificationExtension" } }, - "additionalProperties": false + "additionalProperties": false, + "examples": [ + { + "type": "scramSha512" + } + ] }, "SaslScramSecurityScheme": { "type": "object", @@ -2443,13 +3120,15 @@ "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": { @@ -2457,7 +3136,12 @@ "$ref": "#/definitions/specificationExtension" } }, - "additionalProperties": false + "additionalProperties": false, + "examples": [ + { + "type": "scramSha512" + } + ] }, "SaslGssapiSecurityScheme": { "type": "object", @@ -2467,12 +3151,14 @@ "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": { @@ -2480,7 +3166,12 @@ "$ref": "#/definitions/specificationExtension" } }, - "additionalProperties": false + "additionalProperties": false, + "examples": [ + { + "type": "scramSha512" + } + ] } }, "description": "!!Auto generated!! \n Do not manually edit. " diff --git a/schemas/2.6.0.json b/schemas/2.6.0.json index c05182b5..5ee087dd 100644 --- a/schemas/2.6.0.json +++ b/schemas/2.6.0.json @@ -63,7 +63,7 @@ "http://asyncapi.com/definitions/2.6.0/info.json": { "$id": "http://asyncapi.com/definitions/2.6.0/info.json", "type": "object", - "description": "General information about the API.", + "description": "The object provides metadata about the API. The metadata can be used by the clients if needed.", "required": [ "version", "title" @@ -98,12 +98,28 @@ "license": { "$ref": "http://asyncapi.com/definitions/2.6.0/license.json" } - } + }, + "examples": [ + { + "title": "AsyncAPI Sample App", + "description": "This is a sample server.", + "termsOfService": "https://asyncapi.org/terms/", + "contact": { + "name": "API Support", + "url": "https://www.example.com/support", + "email": "support@example.com" + }, + "license": { + "name": "Apache 2.0", + "url": "https://www.apache.org/licenses/LICENSE-2.0.html" + } + } + ] }, "http://asyncapi.com/definitions/2.6.0/contact.json": { "$id": "http://asyncapi.com/definitions/2.6.0/contact.json", "type": "object", - "description": "Contact information for the owners of the API.", + "description": "Contact information for the exposed API.", "additionalProperties": false, "properties": { "name": { @@ -125,7 +141,14 @@ "^x-[\\w\\d\\.\\x2d_]+$": { "$ref": "http://asyncapi.com/definitions/2.6.0/specificationExtension.json" } - } + }, + "examples": [ + { + "name": "API Support", + "url": "https://www.example.com/support", + "email": "support@example.com" + } + ] }, "http://asyncapi.com/definitions/2.6.0/license.json": { "$id": "http://asyncapi.com/definitions/2.6.0/license.json", @@ -149,7 +172,13 @@ "^x-[\\w\\d\\.\\x2d_]+$": { "$ref": "http://asyncapi.com/definitions/2.6.0/specificationExtension.json" } - } + }, + "examples": [ + { + "name": "Apache 2.0", + "url": "https://www.apache.org/licenses/LICENSE-2.0.html" + } + ] }, "http://asyncapi.com/definitions/2.6.0/servers.json": { "$id": "http://asyncapi.com/definitions/2.6.0/servers.json", @@ -164,7 +193,47 @@ "$ref": "http://asyncapi.com/definitions/2.6.0/server.json" } ] - } + }, + "examples": [ + { + "development": { + "url": "development.gigantic-server.com", + "description": "Development server", + "protocol": "amqp", + "protocolVersion": "0.9.1", + "tags": [ + { + "name": "env:development", + "description": "This environment is meant for developers to run their own tests" + } + ] + }, + "staging": { + "url": "staging.gigantic-server.com", + "description": "Staging server", + "protocol": "amqp", + "protocolVersion": "0.9.1", + "tags": [ + { + "name": "env:staging", + "description": "This environment is a replica of the production environment" + } + ] + }, + "production": { + "url": "api.gigantic-server.com", + "description": "Production server", + "protocol": "amqp", + "protocolVersion": "0.9.1", + "tags": [ + { + "name": "env:production", + "description": "This environment is the live environment available for final users" + } + ] + } + } + ] }, "http://asyncapi.com/definitions/2.6.0/Reference.json": { "$id": "http://asyncapi.com/definitions/2.6.0/Reference.json", @@ -181,12 +250,18 @@ "http://asyncapi.com/definitions/2.6.0/ReferenceObject.json": { "$id": "http://asyncapi.com/definitions/2.6.0/ReferenceObject.json", "type": "string", - "format": "uri-reference" + "description": "A simple object to allow referencing other components in the specification, internally and externally.", + "format": "uri-reference", + "examples": [ + { + "$ref": "#/components/schemas/Pet" + } + ] }, "http://asyncapi.com/definitions/2.6.0/server.json": { "$id": "http://asyncapi.com/definitions/2.6.0/server.json", "type": "object", - "description": "An object representing a Server.", + "description": "An object representing a message broker, a server or any other kind of computer program capable of sending and/or receiving data", "required": [ "url", "protocol" @@ -199,42 +274,58 @@ }, "properties": { "url": { - "type": "string" + "type": "string", + "description": "A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the AsyncAPI document is being served." }, "description": { - "type": "string" + "type": "string", + "description": "An optional string describing the host designated by the URL. CommonMark syntax MAY be used for rich text representation." }, "protocol": { "type": "string", - "description": "The transfer protocol." + "description": "The protocol this URL supports for connection. Supported protocol include, but are not limited to: amqp, amqps, http, https, ibmmq, jms, kafka, kafka-secure, anypointmq, mqtt, secure-mqtt, solace, stomp, stomps, ws, wss, mercure, googlepubsub." }, "protocolVersion": { - "type": "string" + "type": "string", + "description": "The version of the protocol used for connection. For instance: AMQP 0.9.1, HTTP 2.0, Kafka 1.0.0, etc." }, "variables": { + "description": "A map between a variable name and its value. The value is used for substitution in the server's URL template.", "$ref": "http://asyncapi.com/definitions/2.6.0/serverVariables.json" }, "security": { "type": "array", + "description": "A declaration of which security mechanisms can be used with this server. The list of values includes alternative security requirement objects that can be used. ", "items": { "$ref": "http://asyncapi.com/definitions/2.6.0/SecurityRequirement.json" } }, "bindings": { + "description": "A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the server.", "$ref": "http://asyncapi.com/definitions/2.6.0/bindingsObject.json" }, "tags": { "type": "array", + "description": "A list of tags for logical grouping and categorization of servers.", "items": { "$ref": "http://asyncapi.com/definitions/2.6.0/tag.json" }, "uniqueItems": true } - } + }, + "examples": [ + { + "url": "development.gigantic-server.com", + "description": "Development server", + "protocol": "kafka", + "protocolVersion": "1.0.0" + } + ] }, "http://asyncapi.com/definitions/2.6.0/serverVariables.json": { "$id": "http://asyncapi.com/definitions/2.6.0/serverVariables.json", "type": "object", + "description": "A map between a variable name and its value. The value is used for substitution in the server's URL template.", "additionalProperties": { "oneOf": [ { @@ -259,19 +350,23 @@ "properties": { "enum": { "type": "array", + "description": "An enumeration of string values to be used if the substitution options are from a limited set.", "items": { "type": "string" }, "uniqueItems": true }, "default": { - "type": "string" + "type": "string", + "description": "The default value to use for substitution, and to send, if an alternate value is not supplied." }, "description": { - "type": "string" + "type": "string", + "description": "An optional description for the server variable. " }, "examples": { "type": "array", + "description": "An array of examples of the server variable.", "items": { "type": "string" } @@ -281,17 +376,27 @@ "http://asyncapi.com/definitions/2.6.0/SecurityRequirement.json": { "$id": "http://asyncapi.com/definitions/2.6.0/SecurityRequirement.json", "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 - } + }, + "examples": [ + { + "petstore_auth": [ + "write:pets", + "read:pets" + ] + } + ] }, "http://asyncapi.com/definitions/2.6.0/bindingsObject.json": { "$id": "http://asyncapi.com/definitions/2.6.0/bindingsObject.json", "type": "object", + "description": "Map describing protocol-specific definitions for a server.", "additionalProperties": true, "properties": { "http": {}, @@ -317,18 +422,22 @@ "http://asyncapi.com/definitions/2.6.0/tag.json": { "$id": "http://asyncapi.com/definitions/2.6.0/tag.json", "type": "object", + "description": "Allows adding meta data to a single tag.", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { - "type": "string" + "type": "string", + "description": "The name of the tag." }, "description": { - "type": "string" + "type": "string", + "description": "A short description for the tag." }, "externalDocs": { + "description": "Additional external documentation for this tag.", "$ref": "http://asyncapi.com/definitions/2.6.0/externalDocs.json" } }, @@ -336,34 +445,49 @@ "^x-[\\w\\d\\.\\x2d_]+$": { "$ref": "http://asyncapi.com/definitions/2.6.0/specificationExtension.json" } - } + }, + "examples": [ + { + "name": "user", + "description": "User-related messages" + } + ] }, "http://asyncapi.com/definitions/2.6.0/externalDocs.json": { "$id": "http://asyncapi.com/definitions/2.6.0/externalDocs.json", "type": "object", "additionalProperties": false, - "description": "information about external documentation", + "description": "Allows referencing an external resource for extended documentation.", "required": [ "url" ], "properties": { "description": { - "type": "string" + "type": "string", + "description": "A short description of the target documentation." }, "url": { "type": "string", - "format": "uri" + "format": "uri", + "description": "The URL for the target documentation. This MUST be in the form of an absolute URL." } }, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { "$ref": "http://asyncapi.com/definitions/2.6.0/specificationExtension.json" } - } + }, + "examples": [ + { + "description": "Find more info here", + "url": "https://example.com" + } + ] }, "http://asyncapi.com/definitions/2.6.0/channels.json": { "$id": "http://asyncapi.com/definitions/2.6.0/channels.json", "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", @@ -371,11 +495,23 @@ }, "additionalProperties": { "$ref": "http://asyncapi.com/definitions/2.6.0/channelItem.json" - } + }, + "examples": [ + { + "user/signedup": { + "subscribe": { + "message": { + "$ref": "#/components/messages/userSignedUp" + } + } + } + } + ] }, "http://asyncapi.com/definitions/2.6.0/channelItem.json": { "$id": "http://asyncapi.com/definitions/2.6.0/channelItem.json", "type": "object", + "description": "Describes the operations available on a single channel.", "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { @@ -414,11 +550,73 @@ "bindings": { "$ref": "http://asyncapi.com/definitions/2.6.0/bindingsObject.json" } - } + }, + "examples": [ + { + "description": "This channel is used to exchange messages about users signing up", + "subscribe": { + "summary": "A user signed up.", + "message": { + "description": "A longer description of the message", + "payload": { + "type": "object", + "properties": { + "user": { + "$ref": "#/components/schemas/user" + }, + "signup": { + "$ref": "#/components/schemas/signup" + } + } + } + } + }, + "bindings": { + "amqp": { + "is": "queue", + "queue": { + "exclusive": true + } + } + } + }, + { + "subscribe": { + "message": { + "oneOf": [ + { + "$ref": "#/components/messages/signup" + }, + { + "$ref": "#/components/messages/login" + } + ] + } + } + }, + { + "description": "This application publishes WebUICommand messages to an AMQP queue on RabbitMQ brokers in the Staging and Production environments.", + "servers": [ + "rabbitmqBrokerInProd", + "rabbitmqBrokerInStaging" + ], + "subscribe": { + "message": { + "$ref": "#/components/messages/WebUICommand" + } + }, + "bindings": { + "amqp": { + "is": "queue" + } + } + } + ] }, "http://asyncapi.com/definitions/2.6.0/parameters.json": { "$id": "http://asyncapi.com/definitions/2.6.0/parameters.json", "type": "object", + "description": "JSON objects describing re-usable channel parameters.", "additionalProperties": { "oneOf": [ { @@ -429,10 +627,29 @@ } ] }, - "description": "JSON objects describing re-usable channel parameters." + "examples": [ + { + "user/{userId}/signup": { + "parameters": { + "userId": { + "description": "Id of the user.", + "schema": { + "type": "string" + } + } + }, + "subscribe": { + "message": { + "$ref": "#/components/messages/userSignedUp" + } + } + } + } + ] }, "http://asyncapi.com/definitions/2.6.0/parameter.json": { "$id": "http://asyncapi.com/definitions/2.6.0/parameter.json", + "description": "Describes a parameter included in a channel name.", "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { @@ -452,10 +669,31 @@ "description": "A runtime expression that specifies the location of the parameter value", "pattern": "^\\$message\\.(header|payload)#(\\/(([^\\/~])|(~[01]))*)*" } - } + }, + "examples": [ + { + "user/{userId}/signup": { + "parameters": { + "userId": { + "description": "Id of the user.", + "schema": { + "type": "string" + }, + "location": "$message.payload#/user/id" + } + }, + "subscribe": { + "message": { + "$ref": "#/components/messages/userSignedUp" + } + } + } + } + ] }, "http://asyncapi.com/definitions/2.6.0/schema.json": { "$id": "http://asyncapi.com/definitions/2.6.0/schema.json", + "description": "The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays.", "allOf": [ { "$ref": "http://json-schema.org/draft-07/schema#" @@ -538,14 +776,42 @@ "$ref": "http://asyncapi.com/definitions/2.6.0/schema.json" }, "discriminator": { - "type": "string" + "type": "string", + "description": "Adds support for polymorphism. The discriminator is the schema property name that is used to differentiate between other schema that inherit this schema. " }, "externalDocs": { + "description": "Additional external documentation for this schema.", "$ref": "http://asyncapi.com/definitions/2.6.0/externalDocs.json" }, "deprecated": { "type": "boolean", - "default": false + "default": false, + "description": "Specifies that a schema is deprecated and SHOULD be transitioned out of usage" + } + } + } + ], + "examples": [ + { + "type": "string", + "format": "email" + }, + { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string" + }, + "address": { + "$ref": "#/components/schemas/Address" + }, + "age": { + "type": "integer", + "format": "int32", + "minimum": 0 } } } @@ -798,6 +1064,7 @@ "http://asyncapi.com/definitions/2.6.0/operation.json": { "$id": "http://asyncapi.com/definitions/2.6.0/operation.json", "type": "object", + "description": "Describes a publish or a subscribe operation. This provides a place to document how and why messages are sent and received.", "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { @@ -807,6 +1074,7 @@ "properties": { "traits": { "type": "array", + "description": "A list of traits to apply to the operation object.", "items": { "oneOf": [ { @@ -819,19 +1087,23 @@ } }, "summary": { - "type": "string" + "type": "string", + "description": "A short summary of what the operation is about." }, "description": { - "type": "string" + "type": "string", + "description": "A verbose explanation of the operation." }, "security": { "type": "array", + "description": "A declaration of which security mechanisms are associated with this operation.", "items": { "$ref": "http://asyncapi.com/definitions/2.6.0/SecurityRequirement.json" } }, "tags": { "type": "array", + "description": "A list of tags for logical grouping and categorization of operations.", "items": { "$ref": "http://asyncapi.com/definitions/2.6.0/tag.json" }, @@ -849,11 +1121,23 @@ "message": { "$ref": "http://asyncapi.com/definitions/2.6.0/message.json" } - } + }, + "examples": [ + { + "user/signedup": { + "subscribe": { + "message": { + "$ref": "#/components/messages/userSignedUp" + } + } + } + } + ] }, "http://asyncapi.com/definitions/2.6.0/operationTrait.json": { "$id": "http://asyncapi.com/definitions/2.6.0/operationTrait.json", "type": "object", + "description": "Describes a trait that MAY be applied to an Operation Object.", "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { @@ -862,13 +1146,16 @@ }, "properties": { "summary": { - "type": "string" + "type": "string", + "description": "A short summary of what the operation is about." }, "description": { - "type": "string" + "type": "string", + "description": "A verbose explanation of the operation." }, "tags": { "type": "array", + "description": "A list of tags for logical grouping and categorization of operations.", "items": { "$ref": "http://asyncapi.com/definitions/2.6.0/tag.json" }, @@ -878,10 +1165,12 @@ "$ref": "http://asyncapi.com/definitions/2.6.0/externalDocs.json" }, "operationId": { - "type": "string" + "type": "string", + "description": "Unique string used to identify the operation. The id MUST be unique among all operations described in the API." }, "security": { "type": "array", + "description": "A declaration of which security mechanisms are associated with this operation. ", "items": { "$ref": "http://asyncapi.com/definitions/2.6.0/SecurityRequirement.json" } @@ -889,7 +1178,16 @@ "bindings": { "$ref": "http://asyncapi.com/definitions/2.6.0/bindingsObject.json" } - } + }, + "examples": [ + { + "bindings": { + "amqp": { + "ack": false + } + } + } + ] }, "http://asyncapi.com/definitions/2.6.0/message.json": { "$id": "http://asyncapi.com/definitions/2.6.0/message.json", @@ -989,6 +1287,7 @@ }, "examples": { "type": "array", + "description": "List of examples.", "items": { "type": "object", "additionalProperties": false, @@ -1014,9 +1313,12 @@ "description": "A brief summary of the message example." }, "headers": { - "type": "object" + "type": "object", + "description": "Schema definition of the application headers." }, - "payload": {} + "payload": { + "description": "Definition of the message payload. It can be of any type" + } } } }, @@ -1167,11 +1469,106 @@ } ] } + ], + "examples": [ + { + "messageId": "userSignup", + "name": "UserSignup", + "title": "User signup", + "summary": "Action to sign a user up.", + "description": "A longer description", + "contentType": "application/json", + "tags": [ + { + "name": "user" + }, + { + "name": "signup" + }, + { + "name": "register" + } + ], + "headers": { + "type": "object", + "properties": { + "correlationId": { + "description": "Correlation ID set by application", + "type": "string" + }, + "applicationInstanceId": { + "description": "Unique identifier for a given instance of the publishing application", + "type": "string" + } + } + }, + "payload": { + "type": "object", + "properties": { + "user": { + "$ref": "#/components/schemas/userCreate" + }, + "signup": { + "$ref": "#/components/schemas/signup" + } + } + }, + "correlationId": { + "description": "Default Correlation ID", + "location": "$message.header#/correlationId" + }, + "traits": [ + { + "$ref": "#/components/messageTraits/commonHeaders" + } + ], + "examples": [ + { + "name": "SimpleSignup", + "summary": "A simple UserSignup example message", + "headers": { + "correlationId": "my-correlation-id", + "applicationInstanceId": "myInstanceId" + }, + "payload": { + "user": { + "someUserKey": "someUserValue" + }, + "signup": { + "someSignupKey": "someSignupValue" + } + } + } + ] + }, + { + "messageId": "userSignup", + "name": "UserSignup", + "title": "User signup", + "summary": "Action to sign a user up.", + "description": "A longer description", + "tags": [ + { + "name": "user" + }, + { + "name": "signup" + }, + { + "name": "register" + } + ], + "schemaFormat": "application/vnd.apache.avro+json;version=1.9.0", + "payload": { + "$ref": "path/to/user-create.avsc#/UserCreate" + } + } ] }, "http://asyncapi.com/definitions/2.6.0/correlationId.json": { "$id": "http://asyncapi.com/definitions/2.6.0/correlationId.json", "type": "object", + "description": "An object that specifies an identifier at design time that can used for message tracing and correlation.", "required": [ "location" ], @@ -1191,11 +1588,18 @@ "description": "A runtime expression that specifies the location of the correlation ID", "pattern": "^\\$message\\.(header|payload)#(\\/(([^\\/~])|(~[01]))*)*" } - } + }, + "examples": [ + { + "description": "Default Correlation ID", + "location": "$message.header#/correlationId" + } + ] }, "http://asyncapi.com/definitions/2.6.0/messageTrait.json": { "$id": "http://asyncapi.com/definitions/2.6.0/messageTrait.json", "type": "object", + "description": "Describes a trait that MAY be applied to a Message Object.", "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { @@ -1204,12 +1608,15 @@ }, "properties": { "schemaFormat": { - "type": "string" + "type": "string", + "description": "A string containing the name of the schema format/language used to define the message payload." }, "contentType": { - "type": "string" + "type": "string", + "description": "The content type to use when encoding/decoding a message's payload." }, "headers": { + "description": "Schema definition of the application headers.", "allOf": [ { "$ref": "http://asyncapi.com/definitions/2.6.0/schema.json" @@ -1224,9 +1631,11 @@ ] }, "messageId": { - "type": "string" + "type": "string", + "description": "Unique string used to identify the message. The id MUST be unique among all messages described in the API." }, "correlationId": { + "description": "Definition of the correlation ID used for message tracing or matching.", "oneOf": [ { "$ref": "http://asyncapi.com/definitions/2.6.0/Reference.json" @@ -1238,6 +1647,7 @@ }, "tags": { "type": "array", + "description": "A list of tags for logical grouping and categorization of messages.", "items": { "$ref": "http://asyncapi.com/definitions/2.6.0/tag.json" }, @@ -1268,14 +1678,51 @@ }, "examples": { "type": "array", + "description": "List of examples.", "items": { - "type": "object" + "type": "object", + "additionalProperties": false, + "anyOf": [ + { + "required": [ + "payload" + ] + }, + { + "required": [ + "headers" + ] + } + ], + "properties": { + "name": { + "type": "string", + "description": "Machine readable name of the message example." + }, + "summary": { + "type": "string", + "description": "A brief summary of the message example." + }, + "headers": { + "type": "object", + "description": "Schema definition of the application headers." + }, + "payload": { + "description": "Definition of the message payload. It can be of any type" + } + } } }, "bindings": { "$ref": "http://asyncapi.com/definitions/2.6.0/bindingsObject.json" } - } + }, + "examples": [ + { + "schemaFormat": "application/vnd.apache.avro+json;version=1.9.0", + "contentType": "application/json" + } + ] }, "http://asyncapi.com/definitions/2.6.0/openapiSchema_3_0.json": { "$id": "http://asyncapi.com/definitions/2.6.0/openapiSchema_3_0.json", @@ -1975,7 +2422,139 @@ "$ref": "http://asyncapi.com/definitions/2.6.0/bindingsObject.json" } } - } + }, + "examples": [ + { + "components": { + "schemas": { + "Category": { + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64" + }, + "name": { + "type": "string" + } + } + }, + "Tag": { + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64" + }, + "name": { + "type": "string" + } + } + } + }, + "servers": { + "development": { + "url": "{stage}.gigantic-server.com:{port}", + "description": "Development server", + "protocol": "amqp", + "protocolVersion": "0.9.1", + "variables": { + "stage": { + "$ref": "#/components/serverVariables/stage" + }, + "port": { + "$ref": "#/components/serverVariables/port" + } + } + } + }, + "serverVariables": { + "stage": { + "default": "demo", + "description": "This value is assigned by the service provider, in this example `gigantic-server.com`" + }, + "port": { + "enum": [ + "8883", + "8884" + ], + "default": "8883" + } + }, + "channels": { + "user/signedup": { + "subscribe": { + "message": { + "$ref": "#/components/messages/userSignUp" + } + } + } + }, + "messages": { + "userSignUp": { + "summary": "Action to sign a user up.", + "description": "Multiline description of what this action does.\nHere you have another line.\n", + "tags": [ + { + "name": "user" + }, + { + "name": "signup" + } + ], + "headers": { + "type": "object", + "properties": { + "applicationInstanceId": { + "description": "Unique identifier for a given instance of the publishing application", + "type": "string" + } + } + }, + "payload": { + "type": "object", + "properties": { + "user": { + "$ref": "#/components/schemas/userCreate" + }, + "signup": { + "$ref": "#/components/schemas/signup" + } + } + } + } + }, + "parameters": { + "userId": { + "description": "Id of the user.", + "schema": { + "type": "string" + } + } + }, + "correlationIds": { + "default": { + "description": "Default Correlation ID", + "location": "$message.header#/correlationId" + } + }, + "messageTraits": { + "commonHeaders": { + "headers": { + "type": "object", + "properties": { + "my-app-header": { + "type": "integer", + "minimum": 0, + "maximum": 100 + } + } + } + } + } + } + } + ] }, "http://asyncapi.com/definitions/2.6.0/schemas.json": { "$id": "http://asyncapi.com/definitions/2.6.0/schemas.json", @@ -1995,6 +2574,7 @@ }, "http://asyncapi.com/definitions/2.6.0/SecurityScheme.json": { "$id": "http://asyncapi.com/definitions/2.6.0/SecurityScheme.json", + "description": "Defines a security scheme that can be used by the operations.", "oneOf": [ { "$ref": "http://asyncapi.com/definitions/2.6.0/userPassword.json" @@ -2023,6 +2603,11 @@ { "$ref": "http://asyncapi.com/definitions/2.6.0/SaslSecurityScheme.json" } + ], + "examples": [ + { + "type": "userPassword" + } ] }, "http://asyncapi.com/definitions/2.6.0/userPassword.json": { @@ -2034,12 +2619,14 @@ "properties": { "type": { "type": "string", + "description": "The type of the security scheme. ", "enum": [ "userPassword" ] }, "description": { - "type": "string" + "type": "string", + "description": "A short description for security scheme." } }, "patternProperties": { @@ -2047,7 +2634,12 @@ "$ref": "http://asyncapi.com/definitions/2.6.0/specificationExtension.json" } }, - "additionalProperties": false + "additionalProperties": false, + "examples": [ + { + "type": "userPassword" + } + ] }, "http://asyncapi.com/definitions/2.6.0/apiKey.json": { "$id": "http://asyncapi.com/definitions/2.6.0/apiKey.json", @@ -2059,19 +2651,22 @@ "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": { @@ -2079,7 +2674,13 @@ "$ref": "http://asyncapi.com/definitions/2.6.0/specificationExtension.json" } }, - "additionalProperties": false + "additionalProperties": false, + "examples": [ + { + "type": "apiKey", + "in": "user" + } + ] }, "http://asyncapi.com/definitions/2.6.0/X509.json": { "$id": "http://asyncapi.com/definitions/2.6.0/X509.json", @@ -2092,10 +2693,12 @@ "type": "string", "enum": [ "X509" - ] + ], + "description": "The type of the security scheme." }, "description": { - "type": "string" + "type": "string", + "description": "A short description for security scheme." } }, "patternProperties": { @@ -2103,7 +2706,12 @@ "$ref": "http://asyncapi.com/definitions/2.6.0/specificationExtension.json" } }, - "additionalProperties": false + "additionalProperties": false, + "examples": [ + { + "type": "X509" + } + ] }, "http://asyncapi.com/definitions/2.6.0/symmetricEncryption.json": { "$id": "http://asyncapi.com/definitions/2.6.0/symmetricEncryption.json", @@ -2114,12 +2722,14 @@ "properties": { "type": { "type": "string", + "description": "The type of the security scheme.", "enum": [ "symmetricEncryption" ] }, "description": { - "type": "string" + "type": "string", + "description": "A short description for security scheme." } }, "patternProperties": { @@ -2127,7 +2737,12 @@ "$ref": "http://asyncapi.com/definitions/2.6.0/specificationExtension.json" } }, - "additionalProperties": false + "additionalProperties": false, + "examples": [ + { + "type": "symmetricEncryption" + } + ] }, "http://asyncapi.com/definitions/2.6.0/asymmetricEncryption.json": { "$id": "http://asyncapi.com/definitions/2.6.0/asymmetricEncryption.json", @@ -2138,12 +2753,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": { @@ -2174,6 +2791,7 @@ "properties": { "scheme": { "type": "string", + "description": "A short description for security scheme.", "enum": [ "bearer" ] @@ -2187,13 +2805,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" ] @@ -2216,21 +2837,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": { @@ -2251,15 +2876,18 @@ "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", @@ -2267,7 +2895,8 @@ ] }, "description": { - "type": "string" + "type": "string", + "description": "A short description for security scheme." } }, "patternProperties": { @@ -2275,11 +2904,19 @@ "$ref": "http://asyncapi.com/definitions/2.6.0/specificationExtension.json" } }, - "additionalProperties": false + "additionalProperties": false, + "examples": [ + { + "type": "httpApiKey", + "name": "api_key", + "in": "header" + } + ] }, "http://asyncapi.com/definitions/2.6.0/oauth2Flows.json": { "$id": "http://asyncapi.com/definitions/2.6.0/oauth2Flows.json", "type": "object", + "description": "Allows configuration of the supported OAuth Flows.", "required": [ "type", "flows" @@ -2287,17 +2924,20 @@ "properties": { "type": { "type": "string", + "description": "A short description for security scheme.", "enum": [ "oauth2" ] }, "description": { - "type": "string" + "type": "string", + "description": "A short description for security scheme." }, "flows": { "type": "object", "properties": { "implicit": { + "description": "Configuration for the OAuth Implicit flow.", "allOf": [ { "$ref": "http://asyncapi.com/definitions/2.6.0/oauth2Flow.json" @@ -2318,6 +2958,7 @@ ] }, "password": { + "description": "Configuration for the OAuth Resource Owner Protected Credentials flow.", "allOf": [ { "$ref": "http://asyncapi.com/definitions/2.6.0/oauth2Flow.json" @@ -2338,6 +2979,7 @@ ] }, "clientCredentials": { + "description": "Configuration for the OAuth Client Credentials flow.", "allOf": [ { "$ref": "http://asyncapi.com/definitions/2.6.0/oauth2Flow.json" @@ -2358,6 +3000,7 @@ ] }, "authorizationCode": { + "description": "Configuration for the OAuth Authorization Code flow.", "allOf": [ { "$ref": "http://asyncapi.com/definitions/2.6.0/oauth2Flow.json" @@ -2384,20 +3027,25 @@ "http://asyncapi.com/definitions/2.6.0/oauth2Flow.json": { "$id": "http://asyncapi.com/definitions/2.6.0/oauth2Flow.json", "type": "object", + "description": "Configuration details for a supported OAuth Flow", "properties": { "authorizationUrl": { "type": "string", - "format": "uri" + "format": "uri", + "description": "The authorization URL to be used for this flow. This MUST be in the form of an absolute URL." }, "tokenUrl": { "type": "string", - "format": "uri" + "format": "uri", + "description": "The token URL to be used for this flow. This MUST be in the form of an absolute URL." }, "refreshUrl": { "type": "string", - "format": "uri" + "format": "uri", + "description": "The URL to be used for obtaining refresh tokens. This MUST be in the form of an absolute URL." }, "scopes": { + "description": "The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it.", "$ref": "http://asyncapi.com/definitions/2.6.0/oauth2Scopes.json" } }, @@ -2406,7 +3054,29 @@ "$ref": "http://asyncapi.com/definitions/2.6.0/specificationExtension.json" } }, - "additionalProperties": false + "additionalProperties": false, + "examples": [ + { + "type": "oauth2", + "flows": { + "implicit": { + "authorizationUrl": "https://example.com/api/oauth/dialog", + "scopes": { + "write:pets": "modify pets in your account", + "read:pets": "read your pets" + } + }, + "authorizationCode": { + "authorizationUrl": "https://example.com/api/oauth/dialog", + "tokenUrl": "https://example.com/api/oauth/token", + "scopes": { + "write:pets": "modify pets in your account", + "read:pets": "read your pets" + } + } + } + } + ] }, "http://asyncapi.com/definitions/2.6.0/oauth2Scopes.json": { "$id": "http://asyncapi.com/definitions/2.6.0/oauth2Scopes.json", @@ -2467,12 +3137,14 @@ "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": { @@ -2480,7 +3152,12 @@ "$ref": "http://asyncapi.com/definitions/2.6.0/specificationExtension.json" } }, - "additionalProperties": false + "additionalProperties": false, + "examples": [ + { + "type": "scramSha512" + } + ] }, "http://asyncapi.com/definitions/2.6.0/SaslScramSecurityScheme.json": { "$id": "http://asyncapi.com/definitions/2.6.0/SaslScramSecurityScheme.json", @@ -2491,13 +3168,15 @@ "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": { @@ -2505,7 +3184,12 @@ "$ref": "http://asyncapi.com/definitions/2.6.0/specificationExtension.json" } }, - "additionalProperties": false + "additionalProperties": false, + "examples": [ + { + "type": "scramSha512" + } + ] }, "http://asyncapi.com/definitions/2.6.0/SaslGssapiSecurityScheme.json": { "$id": "http://asyncapi.com/definitions/2.6.0/SaslGssapiSecurityScheme.json", @@ -2516,12 +3200,14 @@ "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": { @@ -2529,7 +3215,12 @@ "$ref": "http://asyncapi.com/definitions/2.6.0/specificationExtension.json" } }, - "additionalProperties": false + "additionalProperties": false, + "examples": [ + { + "type": "scramSha512" + } + ] } }, "description": "!!Auto generated!! \n Do not manually edit. " diff --git a/scripts/add-new-version.js b/scripts/add-new-version.js index 8a623787..947c5df3 100644 --- a/scripts/add-new-version.js +++ b/scripts/add-new-version.js @@ -1,5 +1,5 @@ /** - * This script adds a new version of the spec, by copying the latest one as baseline. + * This script adds a new version of the spec with examples, by copying the latest one as baseline. */ const exec = require('child_process').exec; const fs = require('fs'); @@ -25,6 +25,7 @@ function execute(command) { async function addNewVersion(newVersion) { const newVersionDir = `./definitions/${newVersion}`; + const newExampleVersionDir = `./examples/${newVersion}`; try { fs.accessSync(newVersionDir); @@ -36,6 +37,10 @@ async function addNewVersion(newVersion) { const latestVersion = (await execute('ls -d ./definitions/* | sort -V -r | head -1 | xargs -n 1 basename')).trim(); await execute(`cp -R ./definitions/${latestVersion} ${newVersionDir}`); + const latestExampleVersion = (await execute('ls -d ./examples/* | sort -V -r | head -1 | xargs -n 1 basename')).trim(); + await execute(`cp -R ./definitions/${latestVersion} ${newVersionDir}`); + await execute(`cp -R ./examples/${latestExampleVersion} ${newExampleVersionDir}`); + // Replace old version numbers with new await execute(`find ${newVersionDir} -name '*.json' -exec sed -i '' "s+${latestVersion}+${newVersion}+g" {} +`); diff --git a/tools/bundler/index.js b/tools/bundler/index.js index 1d3daf1f..df27e8f6 100644 --- a/tools/bundler/index.js +++ b/tools/bundler/index.js @@ -28,7 +28,18 @@ console.log(`Using the following output directory: ${outputDirectory}`); const definitionFiles = definitions.filter((value) => {return !value.includes('asyncapi')}).map((file) => fs.readFileSync(path.resolve(versionDir, file))); const definitionJson = definitionFiles.map((file) => JSON.parse(file)); for (const jsonFile of definitionJson) { - Bundler.add(jsonFile); + if (jsonFile.example) { + // Replaced the example property with the referenced example property + const examples = await loadRefProperties(jsonFile.example); + // Replacing example property with examples is because using example + // to pass an array of example properties is not valid in JSON Schema. + // So replacing it when bundling is the goto solution. + jsonFile.examples = examples; + delete jsonFile.example; + Bundler.add(jsonFile); + } else { + Bundler.add(jsonFile); + } } const filePathToBundle = `file://${versionDir}/asyncapi.json`; const fileToBundle = await Bundler.get(filePathToBundle); @@ -55,6 +66,23 @@ console.log(`Using the following output directory: ${outputDirectory}`); console.log('done'); })(); +/** + * Extract file data from reference file path + */ + +async function loadRefProperties(filePath) { + const schemaPath = filePath.$ref; + // first we need to turn the path to an absolute file path instead of a generic url + const versionPath = schemaPath.split('examples')[1]; + // we append the extracted file path to the examples dir to read the file + try { + const data = await fs.promises.readFile(`../../examples${versionPath}`); + return JSON.parse(data); + }catch(e) { + throw new Error(e); + } + } + /** * we first update definitions from URL to normal names * than update refs to point to new definitions, always inline never remote