From 1b634b990c2973d60dabfb468921dae3622419eb Mon Sep 17 00:00:00 2001 From: alaminthespecial Date: Wed, 26 Jul 2023 16:43:44 -0400 Subject: [PATCH 1/5] hello world tutorial for AsyncApi v3 --- .../tutorials/getting-started/hello-world.md | 162 ++++++++++++++++++ 1 file changed, 162 insertions(+) create mode 100644 pages/docs/tutorials/getting-started/hello-world.md diff --git a/pages/docs/tutorials/getting-started/hello-world.md b/pages/docs/tutorials/getting-started/hello-world.md new file mode 100644 index 00000000000..17e46e19faf --- /dev/null +++ b/pages/docs/tutorials/getting-started/hello-world.md @@ -0,0 +1,162 @@ +--- +title: "Hello world" +date: 2019-04-01T10:56:52+01:00 +menu: + docs: + parent: 'getting-started' +weight: 30 +--- + +Let's define an application that's capable of receiving a "hello {name}" message. + +{`asyncapi: 3.0.0 +info: + title: Hello world application + version: '0.1.0' +channels: + hello: + address: 'hello' + messages: + sayHelloMessage: + payload: + type: string + pattern: '^hello .+$' +operations: + receiveHello: + action: 'receive' + channel: + $ref: '#/channels/hello'`} + +Let's get into the details of this sample specification: + + +{`asyncapi: 3.0.0 +info: + title: Hello world application + version: '0.1.0' +channels: + hello: + address: 'hello' + messages: + sayHelloMessage: + payload: + type: string + pattern: '^hello .+$' +operations: + receiveHello: + action: 'receive' + channel: + $ref: '#/channels/hello'`} + +The first line of the specification starts with the document type `asyncapi` and the version (3.0.0). This line doesn't have to be the first one, but it's a recommended practice. + +{`asyncapi: 3.0.0 +info: + title: Hello world application + version: '0.1.0' +channels: + hello: + address: 'hello' + messages: + sayHelloMessage: + payload: + type: string + pattern: '^hello .+$' +operations: + receiveHello: + action: 'receive' + channel: + $ref: '#/channels/hello'`} + +The `info` object contains the minimum required information about the application. It contains the `title`, which is a memorable name for the API, and the `version`. While it's not mandatory, it's strongly recommended to change the version whenever you make changes to the API. + + +{`asyncapi: 3.0.0 +info: + title: Hello world application + version: '0.1.0' +channels: + hello: + address: 'hello' + messages: + sayHelloMessage: + payload: + type: string + pattern: '^hello .+$' +operations: + receiveHello: + action: 'receive' + channel: + $ref: '#/channels/hello'`} + + +The `channels` section of the specification houses all of the mediums where messages flow through. For example, some systems use `topic`, `event name` or `routing key`. Different kinds of information flow through each channel similar to the analogy of TV channels. + +In this example, you only have one channel called `hello`. The sample application subscribes to this channel to receive `hello {name}` messages. + + +{`asyncapi: 3.0.0 +info: + title: Hello world application + version: '0.1.0' +channels: + hello: + address: 'hello' + messages: + sayHelloMessage: + payload: + type: string + pattern: '^hello .+$' +operations: + receiveHello: + action: 'receive' + channel: + $ref: '#/channels/hello'`} + + +You can read the highlighted lines as: +> This is the `payload` of the `message` that the `Hello world application` is subscribed to. You can pass the value of `address` to the `messages` to the `hello` channel and the `Hello world application` will receive it through `operations` object. + + +{`asyncapi: 3.0.0 +info: + title: Hello world application + version: '0.1.0' +channels: + hello: + address: 'hello' + messages: + sayHelloMessage: + payload: + type: string + pattern: '^hello .+$' +operations: + receiveHello: + action: 'receive' + channel: + $ref: '#/channels/hello'`} + + +The `payload` object defines how the message must be structured. In this example, the message must be a string and match the given regular expression in the format `hello {name}` string. + + +{`asyncapi: 3.0.0 +info: + title: Hello world application + version: '0.1.0' +channels: + hello: + address: 'hello' + messages: + sayHelloMessage: + payload: + type: string + pattern: '^hello .+$' +operations: + receiveHello: + action: 'receive' + channel: + $ref: '#/channels/hello'`} + + +The `operations` object defines the operations that are supported by the API and it receive message from the `receiveHello`. From a7fb363639204f79fa8abb00b601ea68b4919f18 Mon Sep 17 00:00:00 2001 From: Al Amin Muhammad <82694244+alaminthespecial@users.noreply.github.com> Date: Tue, 1 Aug 2023 07:27:21 -0400 Subject: [PATCH 2/5] Update pages/docs/tutorials/getting-started/hello-world.md Co-authored-by: Jonas Lagoni --- pages/docs/tutorials/getting-started/hello-world.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/tutorials/getting-started/hello-world.md b/pages/docs/tutorials/getting-started/hello-world.md index 17e46e19faf..84d0c822d93 100644 --- a/pages/docs/tutorials/getting-started/hello-world.md +++ b/pages/docs/tutorials/getting-started/hello-world.md @@ -27,7 +27,7 @@ operations: channel: $ref: '#/channels/hello'`} -Let's get into the details of this sample specification: +Let's get into the details of this sample AsyncAPI document: {`asyncapi: 3.0.0 From 130311a1e895402862490711ab87cc129432d733 Mon Sep 17 00:00:00 2001 From: alaminthespecial Date: Wed, 2 Aug 2023 04:31:46 -0400 Subject: [PATCH 3/5] hello world tutorial for AsyncApi v3 --- pages/docs/tutorials/getting-started/hello-world.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/pages/docs/tutorials/getting-started/hello-world.md b/pages/docs/tutorials/getting-started/hello-world.md index 84d0c822d93..0957861a86f 100644 --- a/pages/docs/tutorials/getting-started/hello-world.md +++ b/pages/docs/tutorials/getting-started/hello-world.md @@ -115,8 +115,9 @@ operations: You can read the highlighted lines as: -> This is the `payload` of the `message` that the `Hello world application` is subscribed to. You can pass the value of `address` to the `messages` to the `hello` channel and the `Hello world application` will receive it through `operations` object. +> The `channels` section of a configuration file defines the different channels that are available in a system. Each channel has a unique name, and it can have one or more messages. The messages in a channel define the types of messages that can be sent and received on that channel. +In this case, the hello channel has a single message called `sayHelloMessage`. This message has a string payload that must match the pattern `^hello .+$`. This means that the `sayHelloMessage` can be used to send messages that start with the word "hello" followed by any number of other characters. {`asyncapi: 3.0.0 info: From 1561da8105ff46ccb9c187a5a2519d61eed10bb6 Mon Sep 17 00:00:00 2001 From: Lukasz Gornicki Date: Thu, 9 Nov 2023 17:06:03 +0100 Subject: [PATCH 4/5] Update hello-world.md --- .../tutorials/getting-started/hello-world.md | 60 +++---------------- 1 file changed, 8 insertions(+), 52 deletions(-) diff --git a/pages/docs/tutorials/getting-started/hello-world.md b/pages/docs/tutorials/getting-started/hello-world.md index 0957861a86f..177d9eece1a 100644 --- a/pages/docs/tutorials/getting-started/hello-world.md +++ b/pages/docs/tutorials/getting-started/hello-world.md @@ -1,9 +1,5 @@ --- title: "Hello world" -date: 2019-04-01T10:56:52+01:00 -menu: - docs: - parent: 'getting-started' weight: 30 --- @@ -27,6 +23,7 @@ operations: channel: $ref: '#/channels/hello'`} + Let's get into the details of this sample AsyncAPI document: @@ -48,7 +45,9 @@ operations: channel: $ref: '#/channels/hello'`} + The first line of the specification starts with the document type `asyncapi` and the version (3.0.0). This line doesn't have to be the first one, but it's a recommended practice. + {`asyncapi: 3.0.0 info: @@ -68,6 +67,7 @@ operations: channel: $ref: '#/channels/hello'`} + The `info` object contains the minimum required information about the application. It contains the `title`, which is a memorable name for the API, and the `version`. While it's not mandatory, it's strongly recommended to change the version whenever you make changes to the API. @@ -92,53 +92,7 @@ operations: The `channels` section of the specification houses all of the mediums where messages flow through. For example, some systems use `topic`, `event name` or `routing key`. Different kinds of information flow through each channel similar to the analogy of TV channels. -In this example, you only have one channel called `hello`. The sample application subscribes to this channel to receive `hello {name}` messages. - - -{`asyncapi: 3.0.0 -info: - title: Hello world application - version: '0.1.0' -channels: - hello: - address: 'hello' - messages: - sayHelloMessage: - payload: - type: string - pattern: '^hello .+$' -operations: - receiveHello: - action: 'receive' - channel: - $ref: '#/channels/hello'`} - - -You can read the highlighted lines as: -> The `channels` section of a configuration file defines the different channels that are available in a system. Each channel has a unique name, and it can have one or more messages. The messages in a channel define the types of messages that can be sent and received on that channel. - -In this case, the hello channel has a single message called `sayHelloMessage`. This message has a string payload that must match the pattern `^hello .+$`. This means that the `sayHelloMessage` can be used to send messages that start with the word "hello" followed by any number of other characters. - -{`asyncapi: 3.0.0 -info: - title: Hello world application - version: '0.1.0' -channels: - hello: - address: 'hello' - messages: - sayHelloMessage: - payload: - type: string - pattern: '^hello .+$' -operations: - receiveHello: - action: 'receive' - channel: - $ref: '#/channels/hello'`} - - -The `payload` object defines how the message must be structured. In this example, the message must be a string and match the given regular expression in the format `hello {name}` string. +You only have one channel called `hello` and you see what message is available in this channel and how it must be structured. The `payload` object defines that the message must be a string and match the given regular expression in string format like `hello {name}`. {`asyncapi: 3.0.0 @@ -160,4 +114,6 @@ operations: $ref: '#/channels/hello'`} -The `operations` object defines the operations that are supported by the API and it receive message from the `receiveHello`. +The `operations` section is where you describe what the application is doing. Is application a consumer that `receive` messages or producer that `send` messages, or both? Each operation has unique identifier like for example `receiveHello`. + +In above example you see that `Hello world application` is a consumer that listens to `sayHelloMessage` message comming from `hello` channel. In other words, you can say that `Hello world application` subscribes to `hello` topic to `recive` the `sayHelloMessage` message. This AsyncAPI document describes what `Hello world application` is doing, and not what others can do with it. From b3c9b598a9fb10efcf24f9ebea49733b3153d0e5 Mon Sep 17 00:00:00 2001 From: Alejandra Quetzalli Date: Fri, 10 Nov 2023 16:16:02 -0800 Subject: [PATCH 5/5] tw editorial fixes --- pages/docs/tutorials/getting-started/hello-world.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/pages/docs/tutorials/getting-started/hello-world.md b/pages/docs/tutorials/getting-started/hello-world.md index 177d9eece1a..654c809011f 100644 --- a/pages/docs/tutorials/getting-started/hello-world.md +++ b/pages/docs/tutorials/getting-started/hello-world.md @@ -3,7 +3,8 @@ title: "Hello world" weight: 30 --- -Let's define an application that's capable of receiving a "hello {name}" message. +Let's define an application that's capable of receiving a `"hello {name}"` message: + {`asyncapi: 3.0.0 info: @@ -46,7 +47,7 @@ operations: $ref: '#/channels/hello'`} -The first line of the specification starts with the document type `asyncapi` and the version (3.0.0). This line doesn't have to be the first one, but it's a recommended practice. +The first line of the specification starts with the document type `asyncapi` and the version (3.0.0). That line doesn't have to be the first one, but it's a best practice. {`asyncapi: 3.0.0 @@ -92,7 +93,7 @@ operations: The `channels` section of the specification houses all of the mediums where messages flow through. For example, some systems use `topic`, `event name` or `routing key`. Different kinds of information flow through each channel similar to the analogy of TV channels. -You only have one channel called `hello` and you see what message is available in this channel and how it must be structured. The `payload` object defines that the message must be a string and match the given regular expression in string format like `hello {name}`. +You only have one channel called `hello`, and you see what message is available in this channel and how it must be structured. The `payload` object defines that the message must be a string and match the given regular expression in a string format such as `hello {name}`. {`asyncapi: 3.0.0 @@ -114,6 +115,6 @@ operations: $ref: '#/channels/hello'`} -The `operations` section is where you describe what the application is doing. Is application a consumer that `receive` messages or producer that `send` messages, or both? Each operation has unique identifier like for example `receiveHello`. +The `operations` section is where you describe what the application is doing. Each operation has a unique identifier for example, `receiveHello`. -In above example you see that `Hello world application` is a consumer that listens to `sayHelloMessage` message comming from `hello` channel. In other words, you can say that `Hello world application` subscribes to `hello` topic to `recive` the `sayHelloMessage` message. This AsyncAPI document describes what `Hello world application` is doing, and not what others can do with it. +In the above example, you see that the `Hello world application` is a consumer listening to the `sayHelloMessage` message from the `hello` channel. In other words, you can say that the `Hello world application` subscribes to the `hello` topic to `receive` the `sayHelloMessage` message. That AsyncAPI document describes what the `Hello world application` is doing, not what others can do with it.