From 6ecfd5971bc107e651a5b9e31eab8b0aabdcc3ff Mon Sep 17 00:00:00 2001 From: asyncapi-bot Date: Tue, 21 Nov 2023 10:01:23 +0100 Subject: [PATCH] chore(release): v6.0.0-next-major-spec.14 (#451) --- package-lock.json | 214 ++------- package.json | 2 +- schemas/3.0.0-without-$id.json | 841 ++++++++++++++++++++++++++++++--- schemas/3.0.0.json | 841 ++++++++++++++++++++++++++++++--- 4 files changed, 1581 insertions(+), 317 deletions(-) diff --git a/package-lock.json b/package-lock.json index 81808e12..69ebc9b0 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@asyncapi/specs", - "version": "6.0.0-next-major-spec.13", + "version": "6.0.0-next-major-spec.14", "lockfileVersion": 2, "requires": true, "packages": { "": { "name": "@asyncapi/specs", - "version": "6.0.0-next-major-spec.13", + "version": "6.0.0-next-major-spec.14", "license": "Apache-2.0", "dependencies": { "@types/json-schema": "^7.0.11" @@ -2654,16 +2654,6 @@ } }, "dependencies": { - "@babel/code-frame": { - "version": "7.22.13", - "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.22.13.tgz", - "integrity": "sha512-XktuhWlJ5g+3TJXc5upd9Ks1HutSArik6jf2eAjYFyIOf4ej3RN+184cZbzDvbPnuTJIUhPKKJE3cIsYTiAT3w==", - "dev": true, - "requires": { - "@babel/highlight": "^7.22.13", - "chalk": "^2.4.2" - } - }, "@babel/core": { "version": "7.12.13", "resolved": "https://registry.npmjs.org/@babel/core/-/core-7.12.13.tgz", @@ -2740,38 +2730,24 @@ } } }, - "@babel/helper-environment-visitor": { - "version": "7.22.20", - "resolved": "https://registry.npmjs.org/@babel/helper-environment-visitor/-/helper-environment-visitor-7.22.20.tgz", - "integrity": "sha512-zfedSIzFhat/gFhWfHtgWvlec0nqB9YEIVrpuwjruLlXfUSnA8cJB0miHKwqDnQ7d32aKo2xt88/xZptwxbfhA==", - "dev": true + "@babel/helper-function-name": { + "version": "7.12.13", + "resolved": "https://registry.npmjs.org/@babel/helper-function-name/-/helper-function-name-7.12.13.tgz", + "integrity": "sha512-TZvmPn0UOqmvi5G4vvw0qZTpVptGkB1GL61R6lKvrSdIxGm5Pky7Q3fpKiIkQCAtRCBUwB0PaThlx9vebCDSwA==", + "dev": true, + "requires": { + "@babel/helper-get-function-arity": "^7.12.13", + "@babel/template": "^7.12.13", + "@babel/types": "^7.12.13" + } }, - "@babel/helper-hoist-variables": { - "version": "7.22.5", - "resolved": "https://registry.npmjs.org/@babel/helper-hoist-variables/-/helper-hoist-variables-7.22.5.tgz", - "integrity": "sha512-wGjk9QZVzvknA6yKIUURb8zY3grXCcOZt+/7Wcy8O2uctxhplmUPkOdlgoNhmdVee2c92JXbf1xpMtVNbfoxRw==", + "@babel/helper-get-function-arity": { + "version": "7.12.13", + "resolved": "https://registry.npmjs.org/@babel/helper-get-function-arity/-/helper-get-function-arity-7.12.13.tgz", + "integrity": "sha512-DjEVzQNz5LICkzN0REdpD5prGoidvbdYk1BVgRUOINaWJP2t6avB27X1guXK1kXNrX0WMfsrm1A/ZBthYuIMQg==", "dev": true, "requires": { - "@babel/types": "^7.22.5" - }, - "dependencies": { - "@babel/helper-validator-identifier": { - "version": "7.22.20", - "resolved": "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-7.22.20.tgz", - "integrity": "sha512-Y4OZ+ytlatR8AI+8KZfKuL5urKp7qey08ha31L8b3BwewJAoJamTzyvxPR/5D+KkdJCGPq/+8TukHBlY10FX9A==", - "dev": true - }, - "@babel/types": { - "version": "7.23.0", - "resolved": "https://registry.npmjs.org/@babel/types/-/types-7.23.0.tgz", - "integrity": "sha512-0oIyUfKoI3mSqMvsxBdclDwxXKXAUA8v/apZbc+iSyARYou1o8ZGDxbUYyLFoW2arqS2jDGqJuZvv1d/io1axg==", - "dev": true, - "requires": { - "@babel/helper-string-parser": "^7.22.5", - "@babel/helper-validator-identifier": "^7.22.20", - "to-fast-properties": "^2.0.0" - } - } + "@babel/types": "^7.12.13" } }, "@babel/helper-member-expression-to-functions": { @@ -2848,12 +2824,6 @@ "@babel/types": "^7.12.13" } }, - "@babel/helper-string-parser": { - "version": "7.22.5", - "resolved": "https://registry.npmjs.org/@babel/helper-string-parser/-/helper-string-parser-7.22.5.tgz", - "integrity": "sha512-mM4COjgZox8U+JcXQwPijIZLElkgEpO5rsERVDJTc2qfCDfERyob6k5WegS14SX18IIjv+XD+GrqNumY5JRCDw==", - "dev": true - }, "@babel/helper-validator-identifier": { "version": "7.12.11", "resolved": "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-7.12.11.tgz", @@ -2871,25 +2841,6 @@ "@babel/types": "^7.12.13" } }, - "@babel/highlight": { - "version": "7.22.20", - "resolved": "https://registry.npmjs.org/@babel/highlight/-/highlight-7.22.20.tgz", - "integrity": "sha512-dkdMCN3py0+ksCgYmGG8jKeGA/8Tk+gJwSYYlFGxG5lmhfKNoAy004YpLxpS1W2J8m/EK2Ew+yOs9pVRwO89mg==", - "dev": true, - "requires": { - "@babel/helper-validator-identifier": "^7.22.20", - "chalk": "^2.4.2", - "js-tokens": "^4.0.0" - }, - "dependencies": { - "@babel/helper-validator-identifier": { - "version": "7.22.20", - "resolved": "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-7.22.20.tgz", - "integrity": "sha512-Y4OZ+ytlatR8AI+8KZfKuL5urKp7qey08ha31L8b3BwewJAoJamTzyvxPR/5D+KkdJCGPq/+8TukHBlY10FX9A==", - "dev": true - } - } - }, "@babel/parser": { "version": "7.12.13", "resolved": "https://registry.npmjs.org/@babel/parser/-/parser-7.12.13.tgz", @@ -2930,86 +2881,40 @@ } }, "@babel/traverse": { - "version": "7.23.2", - "resolved": "https://registry.npmjs.org/@babel/traverse/-/traverse-7.23.2.tgz", - "integrity": "sha512-azpe59SQ48qG6nu2CzcMLbxUudtN+dOM9kDbUqGq3HXUJRlo7i8fvPoxQUzYgLZ4cMVmuZgm8vvBpNeRhd6XSw==", + "version": "7.12.13", + "resolved": "https://registry.npmjs.org/@babel/traverse/-/traverse-7.12.13.tgz", + "integrity": "sha512-3Zb4w7eE/OslI0fTp8c7b286/cQps3+vdLW3UcwC8VSJC6GbKn55aeVVu2QJNuCDoeKyptLOFrPq8WqZZBodyA==", "dev": true, "requires": { - "@babel/code-frame": "^7.22.13", - "@babel/generator": "^7.23.0", - "@babel/helper-environment-visitor": "^7.22.20", - "@babel/helper-function-name": "^7.23.0", - "@babel/helper-hoist-variables": "^7.22.5", - "@babel/helper-split-export-declaration": "^7.22.6", - "@babel/parser": "^7.23.0", - "@babel/types": "^7.23.0", + "@babel/code-frame": "^7.12.13", + "@babel/generator": "^7.12.13", + "@babel/helper-function-name": "^7.12.13", + "@babel/helper-split-export-declaration": "^7.12.13", + "@babel/parser": "^7.12.13", + "@babel/types": "^7.12.13", "debug": "^4.1.0", - "globals": "^11.1.0" + "globals": "^11.1.0", + "lodash": "^4.17.19" }, "dependencies": { - "@babel/generator": { - "version": "7.23.0", - "resolved": "https://registry.npmjs.org/@babel/generator/-/generator-7.23.0.tgz", - "integrity": "sha512-lN85QRR+5IbYrMWM6Y4pE/noaQtg4pNiqeNGX60eqOfo6gtEj6uw/JagelB8vVztSd7R6M5n1+PQkDbHbBRU4g==", - "dev": true, - "requires": { - "@babel/types": "^7.23.0", - "@jridgewell/gen-mapping": "^0.3.2", - "@jridgewell/trace-mapping": "^0.3.17", - "jsesc": "^2.5.1" - } - }, - "@babel/helper-function-name": { - "version": "7.23.0", - "resolved": "https://registry.npmjs.org/@babel/helper-function-name/-/helper-function-name-7.23.0.tgz", - "integrity": "sha512-OErEqsrxjZTJciZ4Oo+eoZqeW9UIiOcuYKRJA4ZAgV9myA+pOXhhmpfNCKjEH/auVfEYVFJ6y1Tc4r0eIApqiw==", - "dev": true, - "requires": { - "@babel/template": "^7.22.15", - "@babel/types": "^7.23.0" - } - }, - "@babel/helper-split-export-declaration": { - "version": "7.22.6", - "resolved": "https://registry.npmjs.org/@babel/helper-split-export-declaration/-/helper-split-export-declaration-7.22.6.tgz", - "integrity": "sha512-AsUnxuLhRYsisFiaJwvp1QF+I3KjD5FOxut14q/GzovUe6orHLesW2C7d754kRm53h5gqrz6sFl6sxc4BVtE/g==", - "dev": true, - "requires": { - "@babel/types": "^7.22.5" - } - }, - "@babel/helper-validator-identifier": { - "version": "7.22.20", - "resolved": "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-7.22.20.tgz", - "integrity": "sha512-Y4OZ+ytlatR8AI+8KZfKuL5urKp7qey08ha31L8b3BwewJAoJamTzyvxPR/5D+KkdJCGPq/+8TukHBlY10FX9A==", - "dev": true - }, - "@babel/parser": { - "version": "7.23.0", - "resolved": "https://registry.npmjs.org/@babel/parser/-/parser-7.23.0.tgz", - "integrity": "sha512-vvPKKdMemU85V9WE/l5wZEmImpCtLqbnTvqDS2U1fJ96KrxoW7KrXhNsNCblQlg8Ck4b85yxdTyelsMUgFUXiw==", - "dev": true - }, - "@babel/template": { - "version": "7.22.15", - "resolved": "https://registry.npmjs.org/@babel/template/-/template-7.22.15.tgz", - "integrity": "sha512-QPErUVm4uyJa60rkI73qneDacvdvzxshT3kksGqlGWYdOTIUOwJ7RDUL8sGqslY1uXWSL6xMFKEXDS3ox2uF0w==", + "@babel/code-frame": { + "version": "7.12.13", + "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.12.13.tgz", + "integrity": "sha512-HV1Cm0Q3ZrpCR93tkWOYiuYIgLxZXZFVG2VgK+MBWjUqZTundupbfx2aXarXuw5Ko5aMcjtJgbSs4vUGBS5v6g==", "dev": true, "requires": { - "@babel/code-frame": "^7.22.13", - "@babel/parser": "^7.22.15", - "@babel/types": "^7.22.15" + "@babel/highlight": "^7.12.13" } }, - "@babel/types": { - "version": "7.23.0", - "resolved": "https://registry.npmjs.org/@babel/types/-/types-7.23.0.tgz", - "integrity": "sha512-0oIyUfKoI3mSqMvsxBdclDwxXKXAUA8v/apZbc+iSyARYou1o8ZGDxbUYyLFoW2arqS2jDGqJuZvv1d/io1axg==", + "@babel/highlight": { + "version": "7.12.13", + "resolved": "https://registry.npmjs.org/@babel/highlight/-/highlight-7.12.13.tgz", + "integrity": "sha512-kocDQvIbgMKlWxXe9fof3TQ+gkIPOUSEYhJjqUjvKMez3krV7vbzYCDq39Oj11UAVK7JqPVGQPlgE85dPNlQww==", "dev": true, "requires": { - "@babel/helper-string-parser": "^7.22.5", - "@babel/helper-validator-identifier": "^7.22.20", - "to-fast-properties": "^2.0.0" + "@babel/helper-validator-identifier": "^7.12.11", + "chalk": "^2.0.0", + "js-tokens": "^4.0.0" } } } @@ -3095,45 +3000,6 @@ "integrity": "sha512-tsAQNx32a8CoFhjhijUIhI4kccIAgmGhy8LZMZgGfmXcpMbPRUqn5LWmgRttILi6yeGmBJd2xsPkFMs0PzgPCw==", "dev": true }, - "@jridgewell/gen-mapping": { - "version": "0.3.3", - "resolved": "https://registry.npmjs.org/@jridgewell/gen-mapping/-/gen-mapping-0.3.3.tgz", - "integrity": "sha512-HLhSWOLRi875zjjMG/r+Nv0oCW8umGb0BgEhyX3dDX3egwZtB8PqLnjz3yedt8R5StBrzcg4aBpnh8UA9D1BoQ==", - "dev": true, - "requires": { - "@jridgewell/set-array": "^1.0.1", - "@jridgewell/sourcemap-codec": "^1.4.10", - "@jridgewell/trace-mapping": "^0.3.9" - } - }, - "@jridgewell/resolve-uri": { - "version": "3.1.1", - "resolved": "https://registry.npmjs.org/@jridgewell/resolve-uri/-/resolve-uri-3.1.1.tgz", - "integrity": "sha512-dSYZh7HhCDtCKm4QakX0xFpsRDqjjtZf/kjI/v3T3Nwt5r8/qz/M19F9ySyOqU94SXBmeG9ttTul+YnR4LOxFA==", - "dev": true - }, - "@jridgewell/set-array": { - "version": "1.1.2", - "resolved": "https://registry.npmjs.org/@jridgewell/set-array/-/set-array-1.1.2.tgz", - "integrity": "sha512-xnkseuNADM0gt2bs+BvhO0p78Mk762YnZdsuzFV018NoG1Sj1SCQvpSqa7XUaTam5vAGasABV9qXASMKnFMwMw==", - "dev": true - }, - "@jridgewell/sourcemap-codec": { - "version": "1.4.15", - "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.4.15.tgz", - "integrity": "sha512-eF2rxCRulEKXHTRiDrDy6erMYWqNw4LPdQ8UQA4huuxaQsVeRPFl2oM8oDGxMFhJUWZf9McpLtJasDDZb/Bpeg==", - "dev": true - }, - "@jridgewell/trace-mapping": { - "version": "0.3.19", - "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.19.tgz", - "integrity": "sha512-kf37QtfW+Hwx/buWGMPcR60iF9ziHa6r/CZJIHbmcm4+0qrXiVdxegAH0F6yddEVQ7zdkjcGCgCzUu+BcbhQxw==", - "dev": true, - "requires": { - "@jridgewell/resolve-uri": "^3.1.0", - "@jridgewell/sourcemap-codec": "^1.4.14" - } - }, "@types/json-schema": { "version": "7.0.11", "resolved": "https://registry.npmjs.org/@types/json-schema/-/json-schema-7.0.11.tgz", diff --git a/package.json b/package.json index 8969c4ff..37de273c 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@asyncapi/specs", - "version": "6.0.0-next-major-spec.13", + "version": "6.0.0-next-major-spec.14", "description": "AsyncAPI schema versions", "main": "index.js", "types": "index.d.ts", diff --git a/schemas/3.0.0-without-$id.json b/schemas/3.0.0-without-$id.json index 3586d1ec..edb29eb0 100644 --- a/schemas/3.0.0-without-$id.json +++ b/schemas/3.0.0-without-$id.json @@ -30,7 +30,8 @@ "$ref": "#/definitions/servers" }, "defaultContentType": { - "type": "string" + "type": "string", + "description": "Default content type to use when encoding/decoding a message's payload." }, "channels": { "$ref": "#/definitions/channels" @@ -50,7 +51,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" @@ -87,6 +88,7 @@ }, "tags": { "type": "array", + "description": "A list of tags for application API documentation control. Tags can be used for logical grouping of applications.", "items": { "oneOf": [ { @@ -109,11 +111,37 @@ } ] } - } + }, + "examples": [ + { + "title": "AsyncAPI Sample App", + "version": "1.0.1", + "description": "This is a sample app.", + "termsOfService": "https://asyncapi.org/terms/", + "contact": { + "name": "API Support", + "url": "https://www.asyncapi.org/support", + "email": "support@asyncapi.org" + }, + "license": { + "name": "Apache 2.0", + "url": "https://www.apache.org/licenses/LICENSE-2.0.html" + }, + "externalDocs": { + "description": "Find more info here", + "url": "https://www.asyncapi.org" + }, + "tags": [ + { + "name": "e-commerce" + } + ] + } + ] }, "contact": { "type": "object", - "description": "Contact information for the owners of the API.", + "description": "Contact information for the exposed API.", "additionalProperties": false, "properties": { "name": { @@ -135,7 +163,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", @@ -158,18 +193,31 @@ "^x-[\\w\\d\\.\\x2d_]+$": { "$ref": "#/definitions/specificationExtension" } - } + }, + "examples": [ + { + "name": "Apache 2.0", + "url": "https://www.apache.org/licenses/LICENSE-2.0.html" + } + ] }, "Reference": { "type": "object", + "description": "A simple object to allow referencing other components in the specification, internally and externally.", "required": [ "$ref" ], "properties": { "$ref": { + "description": "The reference string.", "$ref": "#/definitions/ReferenceObject" } - } + }, + "examples": [ + { + "$ref": "#/components/schemas/Pet" + } + ] }, "ReferenceObject": { "type": "string", @@ -177,16 +225,19 @@ }, "tag": { "type": "object", + "description": "Allows adding metadata 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. CommonMark syntax can be used for rich text representation." }, "externalDocs": { "oneOf": [ @@ -203,21 +254,29 @@ "^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. CommonMark syntax can be used for rich text representation." }, "url": { "type": "string", + "description": "The URL for the target documentation. This MUST be in the form of an absolute URL.", "format": "uri" } }, @@ -225,7 +284,13 @@ "^x-[\\w\\d\\.\\x2d_]+$": { "$ref": "#/definitions/specificationExtension" } - } + }, + "examples": [ + { + "description": "Find more info here", + "url": "https://example.com" + } + ] }, "servers": { "description": "An object representing multiple servers.", @@ -239,11 +304,51 @@ "$ref": "#/definitions/server" } ] - } + }, + "examples": [ + { + "development": { + "host": "localhost:5672", + "description": "Development AMQP broker.", + "protocol": "amqp", + "protocolVersion": "0-9-1", + "tags": [ + { + "name": "env:development", + "description": "This environment is meant for developers to run their own tests." + } + ] + }, + "staging": { + "host": "rabbitmq-staging.in.mycompany.com:5672", + "description": "RabbitMQ broker for the staging environment.", + "protocol": "amqp", + "protocolVersion": "0-9-1", + "tags": [ + { + "name": "env:staging", + "description": "This environment is a replica of the production environment." + } + ] + }, + "production": { + "host": "rabbitmq.in.mycompany.com:5672", + "description": "RabbitMQ broker for the production environment.", + "protocol": "amqp", + "protocolVersion": "0-9-1", + "tags": [ + { + "name": "env:production", + "description": "This environment is the live environment available for final users." + } + ] + } + } + ] }, "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": [ "host", "protocol" @@ -257,11 +362,11 @@ "properties": { "host": { "type": "string", - "description": "The server host name." + "description": "The server host name. It MAY include the port. This field supports Server Variables. Variable substitutions will be made when a variable is named in {braces}." }, "pathname": { "type": "string", - "description": "The path to a resource in the host." + "description": "The path to a resource in the host. This field supports Server Variables. Variable substitutions will be made when a variable is named in {braces}." }, "title": { "type": "string", @@ -277,10 +382,11 @@ }, "protocol": { "type": "string", - "description": "The transfer protocol." + "description": "The protocol this server supports for connection." }, "protocolVersion": { - "type": "string" + "type": "string", + "description": "An optional string describing the server. CommonMark syntax MAY be used for rich text representation." }, "variables": { "$ref": "#/definitions/serverVariables" @@ -322,7 +428,21 @@ } ] } - } + }, + "examples": [ + { + "host": "kafka.in.mycompany.com:9092", + "description": "Production Kafka broker.", + "protocol": "kafka", + "protocolVersion": "3.2" + }, + { + "host": "rabbitmq.in.mycompany.com:5672", + "pathname": "/production", + "protocol": "amqp", + "description": "Production RabbitMQ broker (uses the `production` vhost)." + } + ] }, "serverVariables": { "type": "object", @@ -349,24 +469,45 @@ "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. CommonMark syntax MAY be used for rich text representation." }, "examples": { "type": "array", + "description": "An array of examples of the server variable.", "items": { "type": "string" } } - } + }, + "examples": [ + { + "host": "rabbitmq.in.mycompany.com:5672", + "pathname": "/{env}", + "protocol": "amqp", + "description": "RabbitMQ broker. Use the `env` variable to point to either `production` or `staging`.", + "variables": { + "env": { + "description": "Environment to connect to. It can be either `production` or `staging`.", + "enum": [ + "production", + "staging" + ] + } + } + } + ] }, "securityRequirements": { "description": "An array representing security requirements.", @@ -383,6 +524,7 @@ } }, "SecurityScheme": { + "description": "Defines a security scheme that can be used by the operations.", "oneOf": [ { "$ref": "#/definitions/userPassword" @@ -411,6 +553,11 @@ { "$ref": "#/definitions/SaslSecurityScheme" } + ], + "examples": [ + { + "type": "userPassword" + } ] }, "userPassword": { @@ -434,7 +581,12 @@ "$ref": "#/definitions/specificationExtension" } }, - "additionalProperties": false + "additionalProperties": false, + "examples": [ + { + "type": "userPassword" + } + ] }, "apiKey": { "type": "object", @@ -445,19 +597,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. CommonMark syntax MAY be used for rich text representation." } }, "patternProperties": { @@ -465,7 +620,13 @@ "$ref": "#/definitions/specificationExtension" } }, - "additionalProperties": false + "additionalProperties": false, + "examples": [ + { + "type": "apiKey", + "in": "user" + } + ] }, "X509": { "type": "object", @@ -488,7 +649,12 @@ "$ref": "#/definitions/specificationExtension" } }, - "additionalProperties": false + "additionalProperties": false, + "examples": [ + { + "type": "X509" + } + ] }, "symmetricEncryption": { "type": "object", @@ -511,7 +677,12 @@ "$ref": "#/definitions/specificationExtension" } }, - "additionalProperties": false + "additionalProperties": false, + "examples": [ + { + "type": "symmetricEncryption" + } + ] }, "asymmetricEncryption": { "type": "object", @@ -521,12 +692,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": { @@ -555,6 +728,7 @@ "properties": { "scheme": { "type": "string", + "description": "A short description for security scheme.", "enum": [ "bearer" ] @@ -568,13 +742,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" ] @@ -596,21 +773,25 @@ "properties": { "scheme": { "type": "string", + "description": "The name of the HTTP Authorization scheme to be used in the Authorization header as defined in RFC7235.", "enum": [ "bearer" ] }, "bearerFormat": { - "type": "string" + "type": "string", + "description": "A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes." }, "type": { "type": "string", + "description": "The type of the security scheme.", "enum": [ "http" ] }, "description": { - "type": "string" + "type": "string", + "description": "A short description for security scheme. CommonMark syntax MAY be used for rich text representation." } }, "patternProperties": { @@ -630,15 +811,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", @@ -646,7 +830,8 @@ ] }, "description": { - "type": "string" + "type": "string", + "description": "A short description for security scheme. CommonMark syntax MAY be used for rich text representation." } }, "patternProperties": { @@ -654,10 +839,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" @@ -665,17 +858,20 @@ "properties": { "type": { "type": "string", + "description": "The type of the 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" @@ -696,6 +892,7 @@ ] }, "password": { + "description": "Configuration for the OAuth Resource Owner Protected Credentials flow.", "allOf": [ { "$ref": "#/definitions/oauth2Flow" @@ -716,6 +913,7 @@ ] }, "clientCredentials": { + "description": "Configuration for the OAuth Client Credentials flow.", "allOf": [ { "$ref": "#/definitions/oauth2Flow" @@ -736,6 +934,7 @@ ] }, "authorizationCode": { + "description": "Configuration for the OAuth Authorization Code flow.", "allOf": [ { "$ref": "#/definitions/oauth2Flow" @@ -768,21 +967,26 @@ }, "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." }, "availableScopes": { - "$ref": "#/definitions/oauth2Scopes" + "$ref": "#/definitions/oauth2Scopes", + "description": "The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it." } }, "patternProperties": { @@ -790,7 +994,17 @@ "$ref": "#/definitions/specificationExtension" } }, - "additionalProperties": false + "additionalProperties": false, + "examples": [ + { + "authorizationUrl": "https://example.com/api/oauth/dialog", + "tokenUrl": "https://example.com/api/oauth/token", + "availableScopes": { + "write:pets": "modify pets in your account", + "read:pets": "read your pets" + } + } + ] }, "oauth2Scopes": { "type": "object", @@ -807,20 +1021,23 @@ "properties": { "type": { "type": "string", + "description": "The type of the security scheme.", "enum": [ "openIdConnect" ] }, "description": { - "type": "string" + "type": "string", + "description": "A short description for security scheme. CommonMark syntax MAY be used for rich text representation." }, "openIdConnectUrl": { "type": "string", - "format": "uri" + "format": "uri", + "description": "OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of an absolute URL." }, "scopes": { "type": "array", - "description": "List of the needed scope names.", + "description": "List of the needed scope names. An empty array means no scopes are needed.", "items": { "type": "string" } @@ -854,12 +1071,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": { @@ -867,7 +1086,12 @@ "$ref": "#/definitions/specificationExtension" } }, - "additionalProperties": false + "additionalProperties": false, + "examples": [ + { + "type": "scramSha512" + } + ] }, "SaslScramSecurityScheme": { "type": "object", @@ -877,13 +1101,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": { @@ -891,7 +1117,12 @@ "$ref": "#/definitions/specificationExtension" } }, - "additionalProperties": false + "additionalProperties": false, + "examples": [ + { + "type": "scramSha512" + } + ] }, "SaslGssapiSecurityScheme": { "type": "object", @@ -901,12 +1132,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": { @@ -914,10 +1147,16 @@ "$ref": "#/definitions/specificationExtension" } }, - "additionalProperties": false + "additionalProperties": false, + "examples": [ + { + "type": "scramSha512" + } + ] }, "serverBindingsObject": { "type": "object", + "description": "Map describing protocol-specific definitions for a server.", "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { @@ -1327,6 +1566,7 @@ ] }, "schema": { + "description": "The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. This object is a superset of the JSON Schema Specification Draft 07. The empty schema (which allows any instance to validate) MAY be represented by the boolean value true and a schema which allows no instance to validate MAY be represented by the boolean value false.", "allOf": [ { "$ref": "#/definitions/json-schema-draft-07-schema" @@ -1409,7 +1649,8 @@ "$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. The property name used MUST be defined at this schema and it MUST be in the required property list. When used, the value MUST be the name of this schema or any schema that inherits it. See Composition and Inheritance for more details." }, "externalDocs": { "oneOf": [ @@ -1423,6 +1664,7 @@ }, "deprecated": { "type": "boolean", + "description": "Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is false.", "default": false } } @@ -1890,6 +2132,7 @@ }, "channels": { "type": "object", + "description": "An object containing all the Channel Object definitions the Application MUST use during runtime.", "additionalProperties": { "oneOf": [ { @@ -1899,10 +2142,23 @@ "$ref": "#/definitions/channel" } ] - } + }, + "examples": [ + { + "userSignedUp": { + "address": "user.signedup", + "messages": { + "userSignedUp": { + "$ref": "#/components/messages/userSignedUp" + } + } + } + } + ] }, "channel": { "type": "object", + "description": "Describes a shared communication channel.", "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { @@ -1945,6 +2201,7 @@ }, "tags": { "type": "array", + "description": "A list of tags for logical grouping of channels.", "items": { "oneOf": [ { @@ -1977,7 +2234,53 @@ } ] } - } + }, + "examples": [ + { + "address": "users.{userId}", + "title": "Users channel", + "description": "This channel is used to exchange messages about user events.", + "messages": { + "userSignedUp": { + "$ref": "#/components/messages/userSignedUp" + }, + "userCompletedOrder": { + "$ref": "#/components/messages/userCompletedOrder" + } + }, + "parameters": { + "userId": { + "$ref": "#/components/parameters/userId" + } + }, + "servers": [ + { + "$ref": "#/servers/rabbitmqInProd" + }, + { + "$ref": "#/servers/rabbitmqInStaging" + } + ], + "bindings": { + "amqp": { + "is": "queue", + "queue": { + "exclusive": true + } + } + }, + "tags": [ + { + "name": "user", + "description": "User-related messages" + } + ], + "externalDocs": { + "description": "Find more info here", + "url": "https://example.com" + } + } + ] }, "channelMessages": { "type": "object", @@ -1995,6 +2298,7 @@ }, "messageObject": { "type": "object", + "description": "Describes a message received on a given channel and operation.", "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { @@ -2003,7 +2307,8 @@ }, "properties": { "contentType": { - "type": "string" + "type": "string", + "description": "The content type to use when encoding/decoding a message's payload. The value MUST be a specific media type (e.g. application/json). When omitted, the value MUST be the one specified on the defaultContentType field." }, "headers": { "$ref": "#/definitions/anySchema" @@ -2067,6 +2372,7 @@ }, "examples": { "type": "array", + "description": "List of examples.", "items": { "type": "object", "additionalProperties": false, @@ -2113,6 +2419,7 @@ }, "traits": { "type": "array", + "description": "A list of traits to apply to the message object. Traits MUST be merged using traits merge mechanism. The resulting object MUST be a valid Message Object.", "items": { "oneOf": [ { @@ -2143,7 +2450,79 @@ ] } } - } + }, + "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" + } + } + } + ] + } + ] }, "anySchema": { "if": { @@ -2160,6 +2539,7 @@ "description": "An object representing either a schema or a multiFormatSchema based on the existence of the 'schema' property. If the property 'schema' is present, use the multi-format schema. Use the default AsyncAPI Schema otherwise." }, "multiFormatSchema": { + "description": "The Multi Format Schema Object represents a schema definition. It differs from the Schema Object in that it supports multiple schema formats or languages (e.g., JSON Schema, Avro, etc.).", "if": { "not": { "type": "object" @@ -2178,6 +2558,7 @@ }, "properties": { "schemaFormat": { + "description": "A string containing the name of the schema format that is used to define the information. If schemaFormat is missing, it MUST default to application/vnd.aai.asyncapi+json;version={{asyncapi}} where {{asyncapi}} matches the AsyncAPI Version String. In such a case, this would make the Multi Format Schema Object equivalent to the Schema Object. When using Reference Object within the schema, the schemaFormat of the resource being referenced MUST match the schemaFormat of the schema that contains the initial reference. For example, if you reference Avro schema, then schemaFormat of referencing resource and the resource being reference MUST match.", "anyOf": [ { "type": "string" @@ -2206,7 +2587,9 @@ } ] }, - "schema": {} + "schema": { + "description": "Definition of the message payload. It can be of any type but defaults to Schema Object. It MUST match the schema format defined in schemaFormat, including the encoding type. E.g., Avro should be inlined as either a YAML or JSON object instead of as a string to be parsed as YAML or JSON. Non-JSON-based schemas (e.g., Protobuf or XSD) MUST be inlined as a string." + } }, "allOf": [ { @@ -2980,6 +3363,7 @@ }, "correlationId": { "type": "object", + "description": "An object that specifies an identifier at design time that can used for message tracing and correlation.", "required": [ "location" ], @@ -2999,10 +3383,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" + } + ] }, "messageBindingsObject": { "type": "object", + "description": "Map describing protocol-specific definitions for a message.", "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { @@ -3773,6 +4164,7 @@ }, "messageTrait": { "type": "object", + "description": "Describes a trait that MAY be applied to a Message Object. This object MAY contain any property from the Message Object, except payload and traits.", "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { @@ -3781,7 +4173,8 @@ }, "properties": { "contentType": { - "type": "string" + "type": "string", + "description": "The content type to use when encoding/decoding a message's payload. The value MUST be a specific media type (e.g. application/json). When omitted, the value MUST be the one specified on the defaultContentType field." }, "headers": { "$ref": "#/definitions/anySchema" @@ -3842,6 +4235,7 @@ }, "examples": { "type": "array", + "description": "List of examples.", "items": { "type": "object" } @@ -3856,7 +4250,12 @@ } ] } - } + }, + "examples": [ + { + "contentType": "application/json" + } + ] }, "parameters": { "type": "object", @@ -3870,9 +4269,20 @@ } ] }, - "description": "JSON objects describing re-usable channel parameters." + "description": "JSON objects describing re-usable channel parameters.", + "examples": [ + { + "address": "user/{userId}/signedup", + "parameters": { + "userId": { + "description": "Id of the user." + } + } + } + ] }, "parameter": { + "description": "Describes a parameter included in a channel address.", "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { @@ -3885,18 +4295,18 @@ "description": "A brief description of the parameter. This could contain examples of use. GitHub Flavored Markdown is allowed." }, "enum": { - "description": "A list of allowed values for the parameter.", + "description": "An enumeration of string values to be used if the substitution options are from a limited set.", "type": "array", "items": { "type": "string" } }, "default": { - "description": "The default value to use for the parameter.", + "description": "The default value to use for substitution, and to send, if an alternate value is not supplied.", "type": "string" }, "examples": { - "description": "List of example values to use for the parameter.", + "description": "An array of examples of the parameter value.", "type": "array", "items": { "type": "string" @@ -3907,10 +4317,22 @@ "description": "A runtime expression that specifies the location of the parameter value", "pattern": "^\\$message\\.(header|payload)#(\\/(([^\\/~])|(~[01]))*)*" } - } + }, + "examples": [ + { + "address": "user/{userId}/signedup", + "parameters": { + "userId": { + "description": "Id of the user.", + "location": "$message.payload#/user/id" + } + } + } + ] }, "channelBindingsObject": { "type": "object", + "description": "Map describing protocol-specific definitions for a channel.", "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { @@ -4877,6 +5299,7 @@ }, "operations": { "type": "object", + "description": "Holds a dictionary with all the operations this application MUST implement.", "additionalProperties": { "oneOf": [ { @@ -4886,10 +5309,45 @@ "$ref": "#/definitions/operation" } ] - } + }, + "examples": [ + { + "onUserSignUp": { + "title": "User sign up", + "summary": "Action to sign a user up.", + "description": "A longer description", + "channel": { + "$ref": "#/channels/userSignup" + }, + "action": "send", + "tags": [ + { + "name": "user" + }, + { + "name": "signup" + }, + { + "name": "register" + } + ], + "bindings": { + "amqp": { + "ack": false + } + }, + "traits": [ + { + "$ref": "#/components/operationTraits/kafka" + } + ] + } + } + ] }, "operation": { "type": "object", + "description": "Describes a specific operation.", "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { @@ -4914,6 +5372,7 @@ }, "messages": { "type": "array", + "description": "A list of $ref pointers pointing to the supported Message Objects that can be processed by this operation. It MUST contain a subset of the messages defined in the channel referenced in this operation. Every message processed by this operation MUST be valid against one, and only one, of the message objects referenced in this list. Please note the messages property value MUST be a list of Reference Objects and, therefore, MUST NOT contain Message Objects. However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience.", "items": { "$ref": "#/definitions/Reference" } @@ -4930,6 +5389,7 @@ }, "traits": { "type": "array", + "description": "A list of traits to apply to the operation object. Traits MUST be merged using traits merge mechanism. The resulting object MUST be a valid Operation Object.", "items": { "oneOf": [ { @@ -4958,6 +5418,7 @@ }, "tags": { "type": "array", + "description": "A list of tags for logical grouping and categorization of operations.", "items": { "oneOf": [ { @@ -4990,10 +5451,69 @@ } ] } - } + }, + "examples": [ + { + "title": "User sign up", + "summary": "Action to sign a user up.", + "description": "A longer description", + "channel": { + "$ref": "#/channels/userSignup" + }, + "action": "send", + "security": [ + { + "petstore_auth": [ + "write:pets", + "read:pets" + ] + } + ], + "tags": [ + { + "name": "user" + }, + { + "name": "signup" + }, + { + "name": "register" + } + ], + "bindings": { + "amqp": { + "ack": false + } + }, + "traits": [ + { + "$ref": "#/components/operationTraits/kafka" + } + ], + "messages": [ + { + "$ref": "/components/messages/userSignedUp" + } + ], + "reply": { + "address": { + "location": "$message.header#/replyTo" + }, + "channel": { + "$ref": "#/channels/userSignupReply" + }, + "messages": [ + { + "$ref": "/components/messages/userSignedUpReply" + } + ] + } + } + ] }, "operationReply": { "type": "object", + "description": "Describes the reply part that MAY be applied to an Operation Object. If an operation implements the request/reply pattern, the reply object represents the response message.", "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { @@ -5016,6 +5536,7 @@ }, "messages": { "type": "array", + "description": "A list of $ref pointers pointing to the supported Message Objects that can be processed by this operation as reply. It MUST contain a subset of the messages defined in the channel referenced in this operation reply. Every message processed by this operation MUST be valid against one, and only one, of the message objects referenced in this list. Please note the messages property value MUST be a list of Reference Objects and, therefore, MUST NOT contain Message Objects. However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience.", "items": { "$ref": "#/definitions/Reference" } @@ -5024,6 +5545,7 @@ }, "operationReplyAddress": { "type": "object", + "description": "An object that specifies where an operation has to send the reply", "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { @@ -5043,10 +5565,17 @@ "type": "string", "description": "An optional description of the address. CommonMark is allowed." } - } + }, + "examples": [ + { + "description": "Consumer inbox", + "location": "$message.header#/replyTo" + } + ] }, "operationTrait": { "type": "object", + "description": "Describes a trait that MAY be applied to an Operation Object. This object MAY contain any property from the Operation Object, except the action, channel and traits ones.", "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { @@ -5055,24 +5584,31 @@ }, "properties": { "title": { + "description": "A human-friendly title for the operation.", "$ref": "#/definitions/operation/properties/title" }, "summary": { + "description": "A short summary of what the operation is about.", "$ref": "#/definitions/operation/properties/summary" }, "description": { + "description": "A verbose explanation of the operation. CommonMark syntax can be used for rich text representation.", "$ref": "#/definitions/operation/properties/description" }, "security": { + "description": "A declaration of which security schemes are associated with this operation. Only one of the security scheme objects MUST be satisfied to authorize an operation. In cases where Server Security also applies, it MUST also be satisfied.", "$ref": "#/definitions/operation/properties/security" }, "tags": { + "description": "A list of tags for logical grouping and categorization of operations.", "$ref": "#/definitions/operation/properties/tags" }, "externalDocs": { + "description": "Additional external documentation for this operation.", "$ref": "#/definitions/operation/properties/externalDocs" }, "bindings": { + "description": "A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation.", "oneOf": [ { "$ref": "#/definitions/Reference" @@ -5082,10 +5618,20 @@ } ] } - } + }, + "examples": [ + { + "bindings": { + "amqp": { + "ack": false + } + } + } + ] }, "operationBindingsObject": { "type": "object", + "description": "Map describing protocol-specific definitions for an operation.", "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { @@ -5968,7 +6514,7 @@ }, "components": { "type": "object", - "description": "An object to hold a set of reusable objects for different aspects of the AsyncAPI Specification.", + "description": "An object to hold 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_]+$": { @@ -5978,6 +6524,7 @@ "properties": { "schemas": { "type": "object", + "description": "An object to hold reusable Schema Object. If this is a Schema Object, then the schemaFormat will be assumed to be 'application/vnd.aai.asyncapi+json;version=asyncapi' where the version is equal to the AsyncAPI Version String.", "patternProperties": { "^[\\w\\d\\.\\-_]+$": { "oneOf": [ @@ -5993,6 +6540,7 @@ }, "servers": { "type": "object", + "description": "An object to hold reusable Server Objects.", "patternProperties": { "^[\\w\\d\\.\\-_]+$": { "oneOf": [ @@ -6008,6 +6556,7 @@ }, "channels": { "type": "object", + "description": "An object to hold reusable Channel Objects.", "patternProperties": { "^[\\w\\d\\.\\-_]+$": { "oneOf": [ @@ -6023,6 +6572,7 @@ }, "serverVariables": { "type": "object", + "description": "An object to hold reusable Server Variable Objects.", "patternProperties": { "^[\\w\\d\\.\\-_]+$": { "oneOf": [ @@ -6053,6 +6603,7 @@ }, "messages": { "type": "object", + "description": "An object to hold reusable Message Objects.", "patternProperties": { "^[\\w\\d\\.\\-_]+$": { "oneOf": [ @@ -6068,6 +6619,7 @@ }, "securitySchemes": { "type": "object", + "description": "An object to hold reusable Security Scheme Objects.", "patternProperties": { "^[\\w\\d\\.\\-_]+$": { "oneOf": [ @@ -6083,6 +6635,7 @@ }, "parameters": { "type": "object", + "description": "An object to hold reusable Parameter Objects.", "patternProperties": { "^[\\w\\d\\.\\-_]+$": { "oneOf": [ @@ -6098,6 +6651,7 @@ }, "correlationIds": { "type": "object", + "description": "An object to hold reusable Correlation ID Objects.", "patternProperties": { "^[\\w\\d\\.\\-_]+$": { "oneOf": [ @@ -6113,6 +6667,7 @@ }, "operationTraits": { "type": "object", + "description": "An object to hold reusable Operation Trait Objects.", "patternProperties": { "^[\\w\\d\\.\\-_]+$": { "oneOf": [ @@ -6128,6 +6683,7 @@ }, "messageTraits": { "type": "object", + "description": "An object to hold reusable Message Trait Objects.", "patternProperties": { "^[\\w\\d\\.\\-_]+$": { "oneOf": [ @@ -6143,6 +6699,7 @@ }, "replies": { "type": "object", + "description": "An object to hold reusable Operation Reply Objects.", "patternProperties": { "^[\\w\\d\\.\\-_]+$": { "oneOf": [ @@ -6158,6 +6715,7 @@ }, "replyAddresses": { "type": "object", + "description": "An object to hold reusable Operation Reply Address Objects.", "patternProperties": { "^[\\w\\d\\.\\-_]+$": { "oneOf": [ @@ -6173,6 +6731,7 @@ }, "serverBindings": { "type": "object", + "description": "An object to hold reusable Server Bindings Objects.", "patternProperties": { "^[\\w\\d\\.\\-_]+$": { "oneOf": [ @@ -6188,6 +6747,7 @@ }, "channelBindings": { "type": "object", + "description": "An object to hold reusable Channel Bindings Objects.", "patternProperties": { "^[\\w\\d\\.\\-_]+$": { "oneOf": [ @@ -6203,6 +6763,7 @@ }, "operationBindings": { "type": "object", + "description": "An object to hold reusable Operation Bindings Objects.", "patternProperties": { "^[\\w\\d\\.\\-_]+$": { "oneOf": [ @@ -6218,6 +6779,7 @@ }, "messageBindings": { "type": "object", + "description": "An object to hold reusable Message Bindings Objects.", "patternProperties": { "^[\\w\\d\\.\\-_]+$": { "oneOf": [ @@ -6233,6 +6795,7 @@ }, "tags": { "type": "object", + "description": "An object to hold reusable Tag Objects.", "patternProperties": { "^[\\w\\d\\.\\-_]+$": { "oneOf": [ @@ -6248,6 +6811,7 @@ }, "externalDocs": { "type": "object", + "description": "An object to hold reusable External Documentation Objects.", "patternProperties": { "^[\\w\\d\\.\\-_]+$": { "oneOf": [ @@ -6261,7 +6825,142 @@ } } } - } + }, + "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" + } + } + }, + "AvroExample": { + "schemaFormat": "application/vnd.apache.avro+json;version=1.9.0", + "schema": { + "$ref": "path/to/user-create.avsc#/UserCreate" + } + } + }, + "servers": { + "development": { + "host": "{stage}.in.mycompany.com:{port}", + "description": "RabbitMQ broker", + "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 `mycompany.com`" + }, + "port": { + "enum": [ + "5671", + "5672" + ], + "default": "5672" + } + }, + "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." + } + }, + "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 + } + } + } + } + } + } + } + ] } }, "description": "!!Auto generated!! \n Do not manually edit. " diff --git a/schemas/3.0.0.json b/schemas/3.0.0.json index 237fb05d..7ea6fb64 100644 --- a/schemas/3.0.0.json +++ b/schemas/3.0.0.json @@ -31,7 +31,8 @@ "$ref": "http://asyncapi.com/definitions/3.0.0/servers.json" }, "defaultContentType": { - "type": "string" + "type": "string", + "description": "Default content type to use when encoding/decoding a message's payload." }, "channels": { "$ref": "http://asyncapi.com/definitions/3.0.0/channels.json" @@ -53,7 +54,7 @@ "http://asyncapi.com/definitions/3.0.0/info.json": { "$id": "http://asyncapi.com/definitions/3.0.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" @@ -90,6 +91,7 @@ }, "tags": { "type": "array", + "description": "A list of tags for application API documentation control. Tags can be used for logical grouping of applications.", "items": { "oneOf": [ { @@ -112,12 +114,38 @@ } ] } - } + }, + "examples": [ + { + "title": "AsyncAPI Sample App", + "version": "1.0.1", + "description": "This is a sample app.", + "termsOfService": "https://asyncapi.org/terms/", + "contact": { + "name": "API Support", + "url": "https://www.asyncapi.org/support", + "email": "support@asyncapi.org" + }, + "license": { + "name": "Apache 2.0", + "url": "https://www.apache.org/licenses/LICENSE-2.0.html" + }, + "externalDocs": { + "description": "Find more info here", + "url": "https://www.asyncapi.org" + }, + "tags": [ + { + "name": "e-commerce" + } + ] + } + ] }, "http://asyncapi.com/definitions/3.0.0/contact.json": { "$id": "http://asyncapi.com/definitions/3.0.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": { @@ -139,7 +167,14 @@ "^x-[\\w\\d\\.\\x2d_]+$": { "$ref": "http://asyncapi.com/definitions/3.0.0/specificationExtension.json" } - } + }, + "examples": [ + { + "name": "API Support", + "url": "https://www.example.com/support", + "email": "support@example.com" + } + ] }, "http://asyncapi.com/definitions/3.0.0/license.json": { "$id": "http://asyncapi.com/definitions/3.0.0/license.json", @@ -163,19 +198,32 @@ "^x-[\\w\\d\\.\\x2d_]+$": { "$ref": "http://asyncapi.com/definitions/3.0.0/specificationExtension.json" } - } + }, + "examples": [ + { + "name": "Apache 2.0", + "url": "https://www.apache.org/licenses/LICENSE-2.0.html" + } + ] }, "http://asyncapi.com/definitions/3.0.0/Reference.json": { "$id": "http://asyncapi.com/definitions/3.0.0/Reference.json", "type": "object", + "description": "A simple object to allow referencing other components in the specification, internally and externally.", "required": [ "$ref" ], "properties": { "$ref": { + "description": "The reference string.", "$ref": "http://asyncapi.com/definitions/3.0.0/ReferenceObject.json" } - } + }, + "examples": [ + { + "$ref": "#/components/schemas/Pet" + } + ] }, "http://asyncapi.com/definitions/3.0.0/ReferenceObject.json": { "$id": "http://asyncapi.com/definitions/3.0.0/ReferenceObject.json", @@ -185,16 +233,19 @@ "http://asyncapi.com/definitions/3.0.0/tag.json": { "$id": "http://asyncapi.com/definitions/3.0.0/tag.json", "type": "object", + "description": "Allows adding metadata 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. CommonMark syntax can be used for rich text representation." }, "externalDocs": { "oneOf": [ @@ -211,22 +262,30 @@ "^x-[\\w\\d\\.\\x2d_]+$": { "$ref": "http://asyncapi.com/definitions/3.0.0/specificationExtension.json" } - } + }, + "examples": [ + { + "name": "user", + "description": "User-related messages" + } + ] }, "http://asyncapi.com/definitions/3.0.0/externalDocs.json": { "$id": "http://asyncapi.com/definitions/3.0.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. CommonMark syntax can be used for rich text representation." }, "url": { "type": "string", + "description": "The URL for the target documentation. This MUST be in the form of an absolute URL.", "format": "uri" } }, @@ -234,7 +293,13 @@ "^x-[\\w\\d\\.\\x2d_]+$": { "$ref": "http://asyncapi.com/definitions/3.0.0/specificationExtension.json" } - } + }, + "examples": [ + { + "description": "Find more info here", + "url": "https://example.com" + } + ] }, "http://asyncapi.com/definitions/3.0.0/servers.json": { "$id": "http://asyncapi.com/definitions/3.0.0/servers.json", @@ -249,12 +314,52 @@ "$ref": "http://asyncapi.com/definitions/3.0.0/server.json" } ] - } + }, + "examples": [ + { + "development": { + "host": "localhost:5672", + "description": "Development AMQP broker.", + "protocol": "amqp", + "protocolVersion": "0-9-1", + "tags": [ + { + "name": "env:development", + "description": "This environment is meant for developers to run their own tests." + } + ] + }, + "staging": { + "host": "rabbitmq-staging.in.mycompany.com:5672", + "description": "RabbitMQ broker for the staging environment.", + "protocol": "amqp", + "protocolVersion": "0-9-1", + "tags": [ + { + "name": "env:staging", + "description": "This environment is a replica of the production environment." + } + ] + }, + "production": { + "host": "rabbitmq.in.mycompany.com:5672", + "description": "RabbitMQ broker for the production environment.", + "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/3.0.0/server.json": { "$id": "http://asyncapi.com/definitions/3.0.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": [ "host", "protocol" @@ -268,11 +373,11 @@ "properties": { "host": { "type": "string", - "description": "The server host name." + "description": "The server host name. It MAY include the port. This field supports Server Variables. Variable substitutions will be made when a variable is named in {braces}." }, "pathname": { "type": "string", - "description": "The path to a resource in the host." + "description": "The path to a resource in the host. This field supports Server Variables. Variable substitutions will be made when a variable is named in {braces}." }, "title": { "type": "string", @@ -288,10 +393,11 @@ }, "protocol": { "type": "string", - "description": "The transfer protocol." + "description": "The protocol this server supports for connection." }, "protocolVersion": { - "type": "string" + "type": "string", + "description": "An optional string describing the server. CommonMark syntax MAY be used for rich text representation." }, "variables": { "$ref": "http://asyncapi.com/definitions/3.0.0/serverVariables.json" @@ -333,7 +439,21 @@ } ] } - } + }, + "examples": [ + { + "host": "kafka.in.mycompany.com:9092", + "description": "Production Kafka broker.", + "protocol": "kafka", + "protocolVersion": "3.2" + }, + { + "host": "rabbitmq.in.mycompany.com:5672", + "pathname": "/production", + "protocol": "amqp", + "description": "Production RabbitMQ broker (uses the `production` vhost)." + } + ] }, "http://asyncapi.com/definitions/3.0.0/serverVariables.json": { "$id": "http://asyncapi.com/definitions/3.0.0/serverVariables.json", @@ -362,24 +482,45 @@ "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. CommonMark syntax MAY be used for rich text representation." }, "examples": { "type": "array", + "description": "An array of examples of the server variable.", "items": { "type": "string" } } - } + }, + "examples": [ + { + "host": "rabbitmq.in.mycompany.com:5672", + "pathname": "/{env}", + "protocol": "amqp", + "description": "RabbitMQ broker. Use the `env` variable to point to either `production` or `staging`.", + "variables": { + "env": { + "description": "Environment to connect to. It can be either `production` or `staging`.", + "enum": [ + "production", + "staging" + ] + } + } + } + ] }, "http://asyncapi.com/definitions/3.0.0/securityRequirements.json": { "$id": "http://asyncapi.com/definitions/3.0.0/securityRequirements.json", @@ -398,6 +539,7 @@ }, "http://asyncapi.com/definitions/3.0.0/SecurityScheme.json": { "$id": "http://asyncapi.com/definitions/3.0.0/SecurityScheme.json", + "description": "Defines a security scheme that can be used by the operations.", "oneOf": [ { "$ref": "http://asyncapi.com/definitions/3.0.0/userPassword.json" @@ -426,6 +568,11 @@ { "$ref": "http://asyncapi.com/definitions/3.0.0/SaslSecurityScheme.json" } + ], + "examples": [ + { + "type": "userPassword" + } ] }, "http://asyncapi.com/definitions/3.0.0/userPassword.json": { @@ -450,7 +597,12 @@ "$ref": "http://asyncapi.com/definitions/3.0.0/specificationExtension.json" } }, - "additionalProperties": false + "additionalProperties": false, + "examples": [ + { + "type": "userPassword" + } + ] }, "http://asyncapi.com/definitions/3.0.0/apiKey.json": { "$id": "http://asyncapi.com/definitions/3.0.0/apiKey.json", @@ -462,19 +614,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. CommonMark syntax MAY be used for rich text representation." } }, "patternProperties": { @@ -482,7 +637,13 @@ "$ref": "http://asyncapi.com/definitions/3.0.0/specificationExtension.json" } }, - "additionalProperties": false + "additionalProperties": false, + "examples": [ + { + "type": "apiKey", + "in": "user" + } + ] }, "http://asyncapi.com/definitions/3.0.0/X509.json": { "$id": "http://asyncapi.com/definitions/3.0.0/X509.json", @@ -506,7 +667,12 @@ "$ref": "http://asyncapi.com/definitions/3.0.0/specificationExtension.json" } }, - "additionalProperties": false + "additionalProperties": false, + "examples": [ + { + "type": "X509" + } + ] }, "http://asyncapi.com/definitions/3.0.0/symmetricEncryption.json": { "$id": "http://asyncapi.com/definitions/3.0.0/symmetricEncryption.json", @@ -530,7 +696,12 @@ "$ref": "http://asyncapi.com/definitions/3.0.0/specificationExtension.json" } }, - "additionalProperties": false + "additionalProperties": false, + "examples": [ + { + "type": "symmetricEncryption" + } + ] }, "http://asyncapi.com/definitions/3.0.0/asymmetricEncryption.json": { "$id": "http://asyncapi.com/definitions/3.0.0/asymmetricEncryption.json", @@ -541,12 +712,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": { @@ -577,6 +750,7 @@ "properties": { "scheme": { "type": "string", + "description": "A short description for security scheme.", "enum": [ "bearer" ] @@ -590,13 +764,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" ] @@ -619,21 +796,25 @@ "properties": { "scheme": { "type": "string", + "description": "The name of the HTTP Authorization scheme to be used in the Authorization header as defined in RFC7235.", "enum": [ "bearer" ] }, "bearerFormat": { - "type": "string" + "type": "string", + "description": "A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes." }, "type": { "type": "string", + "description": "The type of the security scheme.", "enum": [ "http" ] }, "description": { - "type": "string" + "type": "string", + "description": "A short description for security scheme. CommonMark syntax MAY be used for rich text representation." } }, "patternProperties": { @@ -654,15 +835,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", @@ -670,7 +854,8 @@ ] }, "description": { - "type": "string" + "type": "string", + "description": "A short description for security scheme. CommonMark syntax MAY be used for rich text representation." } }, "patternProperties": { @@ -678,11 +863,19 @@ "$ref": "http://asyncapi.com/definitions/3.0.0/specificationExtension.json" } }, - "additionalProperties": false + "additionalProperties": false, + "examples": [ + { + "type": "httpApiKey", + "name": "api_key", + "in": "header" + } + ] }, "http://asyncapi.com/definitions/3.0.0/oauth2Flows.json": { "$id": "http://asyncapi.com/definitions/3.0.0/oauth2Flows.json", "type": "object", + "description": "Allows configuration of the supported OAuth Flows.", "required": [ "type", "flows" @@ -690,17 +883,20 @@ "properties": { "type": { "type": "string", + "description": "The type of the 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/3.0.0/oauth2Flow.json" @@ -721,6 +917,7 @@ ] }, "password": { + "description": "Configuration for the OAuth Resource Owner Protected Credentials flow.", "allOf": [ { "$ref": "http://asyncapi.com/definitions/3.0.0/oauth2Flow.json" @@ -741,6 +938,7 @@ ] }, "clientCredentials": { + "description": "Configuration for the OAuth Client Credentials flow.", "allOf": [ { "$ref": "http://asyncapi.com/definitions/3.0.0/oauth2Flow.json" @@ -761,6 +959,7 @@ ] }, "authorizationCode": { + "description": "Configuration for the OAuth Authorization Code flow.", "allOf": [ { "$ref": "http://asyncapi.com/definitions/3.0.0/oauth2Flow.json" @@ -794,21 +993,26 @@ "http://asyncapi.com/definitions/3.0.0/oauth2Flow.json": { "$id": "http://asyncapi.com/definitions/3.0.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." }, "availableScopes": { - "$ref": "http://asyncapi.com/definitions/3.0.0/oauth2Scopes.json" + "$ref": "http://asyncapi.com/definitions/3.0.0/oauth2Scopes.json", + "description": "The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it." } }, "patternProperties": { @@ -816,7 +1020,17 @@ "$ref": "http://asyncapi.com/definitions/3.0.0/specificationExtension.json" } }, - "additionalProperties": false + "additionalProperties": false, + "examples": [ + { + "authorizationUrl": "https://example.com/api/oauth/dialog", + "tokenUrl": "https://example.com/api/oauth/token", + "availableScopes": { + "write:pets": "modify pets in your account", + "read:pets": "read your pets" + } + } + ] }, "http://asyncapi.com/definitions/3.0.0/oauth2Scopes.json": { "$id": "http://asyncapi.com/definitions/3.0.0/oauth2Scopes.json", @@ -835,20 +1049,23 @@ "properties": { "type": { "type": "string", + "description": "The type of the security scheme.", "enum": [ "openIdConnect" ] }, "description": { - "type": "string" + "type": "string", + "description": "A short description for security scheme. CommonMark syntax MAY be used for rich text representation." }, "openIdConnectUrl": { "type": "string", - "format": "uri" + "format": "uri", + "description": "OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of an absolute URL." }, "scopes": { "type": "array", - "description": "List of the needed scope names.", + "description": "List of the needed scope names. An empty array means no scopes are needed.", "items": { "type": "string" } @@ -884,12 +1101,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": { @@ -897,7 +1116,12 @@ "$ref": "http://asyncapi.com/definitions/3.0.0/specificationExtension.json" } }, - "additionalProperties": false + "additionalProperties": false, + "examples": [ + { + "type": "scramSha512" + } + ] }, "http://asyncapi.com/definitions/3.0.0/SaslScramSecurityScheme.json": { "$id": "http://asyncapi.com/definitions/3.0.0/SaslScramSecurityScheme.json", @@ -908,13 +1132,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": { @@ -922,7 +1148,12 @@ "$ref": "http://asyncapi.com/definitions/3.0.0/specificationExtension.json" } }, - "additionalProperties": false + "additionalProperties": false, + "examples": [ + { + "type": "scramSha512" + } + ] }, "http://asyncapi.com/definitions/3.0.0/SaslGssapiSecurityScheme.json": { "$id": "http://asyncapi.com/definitions/3.0.0/SaslGssapiSecurityScheme.json", @@ -933,12 +1164,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": { @@ -946,11 +1179,17 @@ "$ref": "http://asyncapi.com/definitions/3.0.0/specificationExtension.json" } }, - "additionalProperties": false + "additionalProperties": false, + "examples": [ + { + "type": "scramSha512" + } + ] }, "http://asyncapi.com/definitions/3.0.0/serverBindingsObject.json": { "$id": "http://asyncapi.com/definitions/3.0.0/serverBindingsObject.json", "type": "object", + "description": "Map describing protocol-specific definitions for a server.", "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { @@ -1363,6 +1602,7 @@ }, "http://asyncapi.com/definitions/3.0.0/schema.json": { "$id": "http://asyncapi.com/definitions/3.0.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. This object is a superset of the JSON Schema Specification Draft 07. The empty schema (which allows any instance to validate) MAY be represented by the boolean value true and a schema which allows no instance to validate MAY be represented by the boolean value false.", "allOf": [ { "$ref": "http://json-schema.org/draft-07/schema#" @@ -1445,7 +1685,8 @@ "$ref": "http://asyncapi.com/definitions/3.0.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. The property name used MUST be defined at this schema and it MUST be in the required property list. When used, the value MUST be the name of this schema or any schema that inherits it. See Composition and Inheritance for more details." }, "externalDocs": { "oneOf": [ @@ -1459,6 +1700,7 @@ }, "deprecated": { "type": "boolean", + "description": "Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is false.", "default": false } } @@ -1934,6 +2176,7 @@ "http://asyncapi.com/definitions/3.0.0/channels.json": { "$id": "http://asyncapi.com/definitions/3.0.0/channels.json", "type": "object", + "description": "An object containing all the Channel Object definitions the Application MUST use during runtime.", "additionalProperties": { "oneOf": [ { @@ -1943,11 +2186,24 @@ "$ref": "http://asyncapi.com/definitions/3.0.0/channel.json" } ] - } + }, + "examples": [ + { + "userSignedUp": { + "address": "user.signedup", + "messages": { + "userSignedUp": { + "$ref": "#/components/messages/userSignedUp" + } + } + } + } + ] }, "http://asyncapi.com/definitions/3.0.0/channel.json": { "$id": "http://asyncapi.com/definitions/3.0.0/channel.json", "type": "object", + "description": "Describes a shared communication channel.", "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { @@ -1990,6 +2246,7 @@ }, "tags": { "type": "array", + "description": "A list of tags for logical grouping of channels.", "items": { "oneOf": [ { @@ -2022,7 +2279,53 @@ } ] } - } + }, + "examples": [ + { + "address": "users.{userId}", + "title": "Users channel", + "description": "This channel is used to exchange messages about user events.", + "messages": { + "userSignedUp": { + "$ref": "#/components/messages/userSignedUp" + }, + "userCompletedOrder": { + "$ref": "#/components/messages/userCompletedOrder" + } + }, + "parameters": { + "userId": { + "$ref": "#/components/parameters/userId" + } + }, + "servers": [ + { + "$ref": "#/servers/rabbitmqInProd" + }, + { + "$ref": "#/servers/rabbitmqInStaging" + } + ], + "bindings": { + "amqp": { + "is": "queue", + "queue": { + "exclusive": true + } + } + }, + "tags": [ + { + "name": "user", + "description": "User-related messages" + } + ], + "externalDocs": { + "description": "Find more info here", + "url": "https://example.com" + } + } + ] }, "http://asyncapi.com/definitions/3.0.0/channelMessages.json": { "$id": "http://asyncapi.com/definitions/3.0.0/channelMessages.json", @@ -2042,6 +2345,7 @@ "http://asyncapi.com/definitions/3.0.0/messageObject.json": { "$id": "http://asyncapi.com/definitions/3.0.0/messageObject.json", "type": "object", + "description": "Describes a message received on a given channel and operation.", "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { @@ -2050,7 +2354,8 @@ }, "properties": { "contentType": { - "type": "string" + "type": "string", + "description": "The content type to use when encoding/decoding a message's payload. The value MUST be a specific media type (e.g. application/json). When omitted, the value MUST be the one specified on the defaultContentType field." }, "headers": { "$ref": "http://asyncapi.com/definitions/3.0.0/anySchema.json" @@ -2114,6 +2419,7 @@ }, "examples": { "type": "array", + "description": "List of examples.", "items": { "type": "object", "additionalProperties": false, @@ -2160,6 +2466,7 @@ }, "traits": { "type": "array", + "description": "A list of traits to apply to the message object. Traits MUST be merged using traits merge mechanism. The resulting object MUST be a valid Message Object.", "items": { "oneOf": [ { @@ -2190,7 +2497,79 @@ ] } } - } + }, + "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" + } + } + } + ] + } + ] }, "http://asyncapi.com/definitions/3.0.0/anySchema.json": { "$id": "http://asyncapi.com/definitions/3.0.0/anySchema.json", @@ -2209,6 +2588,7 @@ }, "http://asyncapi.com/definitions/3.0.0/multiFormatSchema.json": { "$id": "http://asyncapi.com/definitions/3.0.0/multiFormatSchema.json", + "description": "The Multi Format Schema Object represents a schema definition. It differs from the Schema Object in that it supports multiple schema formats or languages (e.g., JSON Schema, Avro, etc.).", "if": { "not": { "type": "object" @@ -2227,6 +2607,7 @@ }, "properties": { "schemaFormat": { + "description": "A string containing the name of the schema format that is used to define the information. If schemaFormat is missing, it MUST default to application/vnd.aai.asyncapi+json;version={{asyncapi}} where {{asyncapi}} matches the AsyncAPI Version String. In such a case, this would make the Multi Format Schema Object equivalent to the Schema Object. When using Reference Object within the schema, the schemaFormat of the resource being referenced MUST match the schemaFormat of the schema that contains the initial reference. For example, if you reference Avro schema, then schemaFormat of referencing resource and the resource being reference MUST match.", "anyOf": [ { "type": "string" @@ -2255,7 +2636,9 @@ } ] }, - "schema": {} + "schema": { + "description": "Definition of the message payload. It can be of any type but defaults to Schema Object. It MUST match the schema format defined in schemaFormat, including the encoding type. E.g., Avro should be inlined as either a YAML or JSON object instead of as a string to be parsed as YAML or JSON. Non-JSON-based schemas (e.g., Protobuf or XSD) MUST be inlined as a string." + } }, "allOf": [ { @@ -3032,6 +3415,7 @@ "http://asyncapi.com/definitions/3.0.0/correlationId.json": { "$id": "http://asyncapi.com/definitions/3.0.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" ], @@ -3051,11 +3435,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/3.0.0/messageBindingsObject.json": { "$id": "http://asyncapi.com/definitions/3.0.0/messageBindingsObject.json", "type": "object", + "description": "Map describing protocol-specific definitions for a message.", "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { @@ -3836,6 +4227,7 @@ "http://asyncapi.com/definitions/3.0.0/messageTrait.json": { "$id": "http://asyncapi.com/definitions/3.0.0/messageTrait.json", "type": "object", + "description": "Describes a trait that MAY be applied to a Message Object. This object MAY contain any property from the Message Object, except payload and traits.", "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { @@ -3844,7 +4236,8 @@ }, "properties": { "contentType": { - "type": "string" + "type": "string", + "description": "The content type to use when encoding/decoding a message's payload. The value MUST be a specific media type (e.g. application/json). When omitted, the value MUST be the one specified on the defaultContentType field." }, "headers": { "$ref": "http://asyncapi.com/definitions/3.0.0/anySchema.json" @@ -3905,6 +4298,7 @@ }, "examples": { "type": "array", + "description": "List of examples.", "items": { "type": "object" } @@ -3919,7 +4313,12 @@ } ] } - } + }, + "examples": [ + { + "contentType": "application/json" + } + ] }, "http://asyncapi.com/definitions/3.0.0/parameters.json": { "$id": "http://asyncapi.com/definitions/3.0.0/parameters.json", @@ -3934,10 +4333,21 @@ } ] }, - "description": "JSON objects describing re-usable channel parameters." + "description": "JSON objects describing re-usable channel parameters.", + "examples": [ + { + "address": "user/{userId}/signedup", + "parameters": { + "userId": { + "description": "Id of the user." + } + } + } + ] }, "http://asyncapi.com/definitions/3.0.0/parameter.json": { "$id": "http://asyncapi.com/definitions/3.0.0/parameter.json", + "description": "Describes a parameter included in a channel address.", "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { @@ -3950,18 +4360,18 @@ "description": "A brief description of the parameter. This could contain examples of use. GitHub Flavored Markdown is allowed." }, "enum": { - "description": "A list of allowed values for the parameter.", + "description": "An enumeration of string values to be used if the substitution options are from a limited set.", "type": "array", "items": { "type": "string" } }, "default": { - "description": "The default value to use for the parameter.", + "description": "The default value to use for substitution, and to send, if an alternate value is not supplied.", "type": "string" }, "examples": { - "description": "List of example values to use for the parameter.", + "description": "An array of examples of the parameter value.", "type": "array", "items": { "type": "string" @@ -3972,11 +4382,23 @@ "description": "A runtime expression that specifies the location of the parameter value", "pattern": "^\\$message\\.(header|payload)#(\\/(([^\\/~])|(~[01]))*)*" } - } + }, + "examples": [ + { + "address": "user/{userId}/signedup", + "parameters": { + "userId": { + "description": "Id of the user.", + "location": "$message.payload#/user/id" + } + } + } + ] }, "http://asyncapi.com/definitions/3.0.0/channelBindingsObject.json": { "$id": "http://asyncapi.com/definitions/3.0.0/channelBindingsObject.json", "type": "object", + "description": "Map describing protocol-specific definitions for a channel.", "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { @@ -4952,6 +5374,7 @@ "http://asyncapi.com/definitions/3.0.0/operations.json": { "$id": "http://asyncapi.com/definitions/3.0.0/operations.json", "type": "object", + "description": "Holds a dictionary with all the operations this application MUST implement.", "additionalProperties": { "oneOf": [ { @@ -4961,11 +5384,46 @@ "$ref": "http://asyncapi.com/definitions/3.0.0/operation.json" } ] - } + }, + "examples": [ + { + "onUserSignUp": { + "title": "User sign up", + "summary": "Action to sign a user up.", + "description": "A longer description", + "channel": { + "$ref": "#/channels/userSignup" + }, + "action": "send", + "tags": [ + { + "name": "user" + }, + { + "name": "signup" + }, + { + "name": "register" + } + ], + "bindings": { + "amqp": { + "ack": false + } + }, + "traits": [ + { + "$ref": "#/components/operationTraits/kafka" + } + ] + } + } + ] }, "http://asyncapi.com/definitions/3.0.0/operation.json": { "$id": "http://asyncapi.com/definitions/3.0.0/operation.json", "type": "object", + "description": "Describes a specific operation.", "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { @@ -4990,6 +5448,7 @@ }, "messages": { "type": "array", + "description": "A list of $ref pointers pointing to the supported Message Objects that can be processed by this operation. It MUST contain a subset of the messages defined in the channel referenced in this operation. Every message processed by this operation MUST be valid against one, and only one, of the message objects referenced in this list. Please note the messages property value MUST be a list of Reference Objects and, therefore, MUST NOT contain Message Objects. However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience.", "items": { "$ref": "http://asyncapi.com/definitions/3.0.0/Reference.json" } @@ -5006,6 +5465,7 @@ }, "traits": { "type": "array", + "description": "A list of traits to apply to the operation object. Traits MUST be merged using traits merge mechanism. The resulting object MUST be a valid Operation Object.", "items": { "oneOf": [ { @@ -5034,6 +5494,7 @@ }, "tags": { "type": "array", + "description": "A list of tags for logical grouping and categorization of operations.", "items": { "oneOf": [ { @@ -5066,11 +5527,70 @@ } ] } - } + }, + "examples": [ + { + "title": "User sign up", + "summary": "Action to sign a user up.", + "description": "A longer description", + "channel": { + "$ref": "#/channels/userSignup" + }, + "action": "send", + "security": [ + { + "petstore_auth": [ + "write:pets", + "read:pets" + ] + } + ], + "tags": [ + { + "name": "user" + }, + { + "name": "signup" + }, + { + "name": "register" + } + ], + "bindings": { + "amqp": { + "ack": false + } + }, + "traits": [ + { + "$ref": "#/components/operationTraits/kafka" + } + ], + "messages": [ + { + "$ref": "/components/messages/userSignedUp" + } + ], + "reply": { + "address": { + "location": "$message.header#/replyTo" + }, + "channel": { + "$ref": "#/channels/userSignupReply" + }, + "messages": [ + { + "$ref": "/components/messages/userSignedUpReply" + } + ] + } + } + ] }, "http://asyncapi.com/definitions/3.0.0/operationReply.json": { "$id": "http://asyncapi.com/definitions/3.0.0/operationReply.json", "type": "object", + "description": "Describes the reply part that MAY be applied to an Operation Object. If an operation implements the request/reply pattern, the reply object represents the response message.", "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { @@ -5093,6 +5613,7 @@ }, "messages": { "type": "array", + "description": "A list of $ref pointers pointing to the supported Message Objects that can be processed by this operation as reply. It MUST contain a subset of the messages defined in the channel referenced in this operation reply. Every message processed by this operation MUST be valid against one, and only one, of the message objects referenced in this list. Please note the messages property value MUST be a list of Reference Objects and, therefore, MUST NOT contain Message Objects. However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience.", "items": { "$ref": "http://asyncapi.com/definitions/3.0.0/Reference.json" } @@ -5102,6 +5623,7 @@ "http://asyncapi.com/definitions/3.0.0/operationReplyAddress.json": { "$id": "http://asyncapi.com/definitions/3.0.0/operationReplyAddress.json", "type": "object", + "description": "An object that specifies where an operation has to send the reply", "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { @@ -5121,11 +5643,18 @@ "type": "string", "description": "An optional description of the address. CommonMark is allowed." } - } + }, + "examples": [ + { + "description": "Consumer inbox", + "location": "$message.header#/replyTo" + } + ] }, "http://asyncapi.com/definitions/3.0.0/operationTrait.json": { "$id": "http://asyncapi.com/definitions/3.0.0/operationTrait.json", "type": "object", + "description": "Describes a trait that MAY be applied to an Operation Object. This object MAY contain any property from the Operation Object, except the action, channel and traits ones.", "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { @@ -5134,24 +5663,31 @@ }, "properties": { "title": { + "description": "A human-friendly title for the operation.", "$ref": "http://asyncapi.com/definitions/3.0.0/operation.json#/properties/title" }, "summary": { + "description": "A short summary of what the operation is about.", "$ref": "http://asyncapi.com/definitions/3.0.0/operation.json#/properties/summary" }, "description": { + "description": "A verbose explanation of the operation. CommonMark syntax can be used for rich text representation.", "$ref": "http://asyncapi.com/definitions/3.0.0/operation.json#/properties/description" }, "security": { + "description": "A declaration of which security schemes are associated with this operation. Only one of the security scheme objects MUST be satisfied to authorize an operation. In cases where Server Security also applies, it MUST also be satisfied.", "$ref": "http://asyncapi.com/definitions/3.0.0/operation.json#/properties/security" }, "tags": { + "description": "A list of tags for logical grouping and categorization of operations.", "$ref": "http://asyncapi.com/definitions/3.0.0/operation.json#/properties/tags" }, "externalDocs": { + "description": "Additional external documentation for this operation.", "$ref": "http://asyncapi.com/definitions/3.0.0/operation.json#/properties/externalDocs" }, "bindings": { + "description": "A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation.", "oneOf": [ { "$ref": "http://asyncapi.com/definitions/3.0.0/Reference.json" @@ -5161,11 +5697,21 @@ } ] } - } + }, + "examples": [ + { + "bindings": { + "amqp": { + "ack": false + } + } + } + ] }, "http://asyncapi.com/definitions/3.0.0/operationBindingsObject.json": { "$id": "http://asyncapi.com/definitions/3.0.0/operationBindingsObject.json", "type": "object", + "description": "Map describing protocol-specific definitions for an operation.", "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\x2d_]+$": { @@ -6058,7 +6604,7 @@ "http://asyncapi.com/definitions/3.0.0/components.json": { "$id": "http://asyncapi.com/definitions/3.0.0/components.json", "type": "object", - "description": "An object to hold a set of reusable objects for different aspects of the AsyncAPI Specification.", + "description": "An object to hold 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_]+$": { @@ -6068,6 +6614,7 @@ "properties": { "schemas": { "type": "object", + "description": "An object to hold reusable Schema Object. If this is a Schema Object, then the schemaFormat will be assumed to be 'application/vnd.aai.asyncapi+json;version=asyncapi' where the version is equal to the AsyncAPI Version String.", "patternProperties": { "^[\\w\\d\\.\\-_]+$": { "oneOf": [ @@ -6083,6 +6630,7 @@ }, "servers": { "type": "object", + "description": "An object to hold reusable Server Objects.", "patternProperties": { "^[\\w\\d\\.\\-_]+$": { "oneOf": [ @@ -6098,6 +6646,7 @@ }, "channels": { "type": "object", + "description": "An object to hold reusable Channel Objects.", "patternProperties": { "^[\\w\\d\\.\\-_]+$": { "oneOf": [ @@ -6113,6 +6662,7 @@ }, "serverVariables": { "type": "object", + "description": "An object to hold reusable Server Variable Objects.", "patternProperties": { "^[\\w\\d\\.\\-_]+$": { "oneOf": [ @@ -6143,6 +6693,7 @@ }, "messages": { "type": "object", + "description": "An object to hold reusable Message Objects.", "patternProperties": { "^[\\w\\d\\.\\-_]+$": { "oneOf": [ @@ -6158,6 +6709,7 @@ }, "securitySchemes": { "type": "object", + "description": "An object to hold reusable Security Scheme Objects.", "patternProperties": { "^[\\w\\d\\.\\-_]+$": { "oneOf": [ @@ -6173,6 +6725,7 @@ }, "parameters": { "type": "object", + "description": "An object to hold reusable Parameter Objects.", "patternProperties": { "^[\\w\\d\\.\\-_]+$": { "oneOf": [ @@ -6188,6 +6741,7 @@ }, "correlationIds": { "type": "object", + "description": "An object to hold reusable Correlation ID Objects.", "patternProperties": { "^[\\w\\d\\.\\-_]+$": { "oneOf": [ @@ -6203,6 +6757,7 @@ }, "operationTraits": { "type": "object", + "description": "An object to hold reusable Operation Trait Objects.", "patternProperties": { "^[\\w\\d\\.\\-_]+$": { "oneOf": [ @@ -6218,6 +6773,7 @@ }, "messageTraits": { "type": "object", + "description": "An object to hold reusable Message Trait Objects.", "patternProperties": { "^[\\w\\d\\.\\-_]+$": { "oneOf": [ @@ -6233,6 +6789,7 @@ }, "replies": { "type": "object", + "description": "An object to hold reusable Operation Reply Objects.", "patternProperties": { "^[\\w\\d\\.\\-_]+$": { "oneOf": [ @@ -6248,6 +6805,7 @@ }, "replyAddresses": { "type": "object", + "description": "An object to hold reusable Operation Reply Address Objects.", "patternProperties": { "^[\\w\\d\\.\\-_]+$": { "oneOf": [ @@ -6263,6 +6821,7 @@ }, "serverBindings": { "type": "object", + "description": "An object to hold reusable Server Bindings Objects.", "patternProperties": { "^[\\w\\d\\.\\-_]+$": { "oneOf": [ @@ -6278,6 +6837,7 @@ }, "channelBindings": { "type": "object", + "description": "An object to hold reusable Channel Bindings Objects.", "patternProperties": { "^[\\w\\d\\.\\-_]+$": { "oneOf": [ @@ -6293,6 +6853,7 @@ }, "operationBindings": { "type": "object", + "description": "An object to hold reusable Operation Bindings Objects.", "patternProperties": { "^[\\w\\d\\.\\-_]+$": { "oneOf": [ @@ -6308,6 +6869,7 @@ }, "messageBindings": { "type": "object", + "description": "An object to hold reusable Message Bindings Objects.", "patternProperties": { "^[\\w\\d\\.\\-_]+$": { "oneOf": [ @@ -6323,6 +6885,7 @@ }, "tags": { "type": "object", + "description": "An object to hold reusable Tag Objects.", "patternProperties": { "^[\\w\\d\\.\\-_]+$": { "oneOf": [ @@ -6338,6 +6901,7 @@ }, "externalDocs": { "type": "object", + "description": "An object to hold reusable External Documentation Objects.", "patternProperties": { "^[\\w\\d\\.\\-_]+$": { "oneOf": [ @@ -6351,7 +6915,142 @@ } } } - } + }, + "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" + } + } + }, + "AvroExample": { + "schemaFormat": "application/vnd.apache.avro+json;version=1.9.0", + "schema": { + "$ref": "path/to/user-create.avsc#/UserCreate" + } + } + }, + "servers": { + "development": { + "host": "{stage}.in.mycompany.com:{port}", + "description": "RabbitMQ broker", + "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 `mycompany.com`" + }, + "port": { + "enum": [ + "5671", + "5672" + ], + "default": "5672" + } + }, + "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." + } + }, + "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 + } + } + } + } + } + } + } + ] } }, "description": "!!Auto generated!! \n Do not manually edit. "