Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix: modifies docs to support asynapi v3 #612

Merged
merged 3 commits into from
Dec 4, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 35 additions & 26 deletions docs/pages/glee-template.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,26 +5,29 @@ weight: 170
This tutorial teaches you how to create a simple glee template. You'll use the AsyncAPI Glee template you develop to generate Javascript code. Additionally, you'll create a template code with a reusable component to reuse the custom functionality you create and test your code using an WS server.

<CodeBlock>
{`asyncapi: '2.1.0'
{`asyncapi: 3.0.0
info:
title: Hello, Glee!
version: 0.1.0

title: 'Hello, Glee!'
version: 1.0.0
servers:
websockets:
url: ws://0.0.0.0:3000
host: 0.0.0.0:3000
protocol: ws

channels:
hello:
publish:
operationId: onHello
message:
$ref: '#/components/messages/hello'
subscribe:
message:
address: hello
messages:
hello:
$ref: '#/components/messages/hello'

operations:
onHello:
action: receive
channel:
$ref: '#/channels/hello'
sendHello:
action: send
channel:
$ref: '#/channels/hello'
components:
messages:
hello:
Expand All @@ -36,8 +39,8 @@ Let's break it down into pieces:

<CodeBlock>
{`info:
title: Hello, Glee!
version: 0.1.0`}
title: 'Hello, Glee!'
version: 1.0.0`}
</CodeBlock>

The `info` section provides general information about the API, including its title and version.
Expand All @@ -46,8 +49,8 @@ Moving on, let's talk about the `servers` section.

<CodeBlock>
{`servers:
mosquitto:
url: ws://0.0.0.0:3000
websockets:
host: 0.0.0.0:3000
protocol: ws`}
</CodeBlock>

Expand All @@ -58,19 +61,25 @@ Now lets move on to the `channels` section. This section is used to describe the
<CodeBlock>
{`channels:
hello:
publish:
operationId: onHello
message:
address: hello
messages:
hello:
$ref: '#/components/messages/hello'
subscribe:
message:
$ref: '#/components/messages/hello'`}
operations:
onHello:
action: receive
channel:
$ref: '#/channels/hello'
sendHello:
action: send
channel:
$ref: '#/channels/hello'`}
</CodeBlock>

The channels section defines the communication channels available in the API. In this case, there's a channel named "hello". This channel supports both publishing and subscribing.
The channels section defines the communication channels available in the API. In this case, there's a channel named "hello". This channel supports both sending and receiving.

The `publish` section specifies that the operation with ID onHello is used for publishing to the `hello` channel. The message structure is referenced from the hello message component.
The `subscribe` section indicates that messages received on the `hello` channel should follow the structure defined in the hello message component.
The `receive` action indicates that messages received on the `hello` channel should follow the structure defined in the hello message component.
The `send` action specifies that the operation with ID `sendHello` is used for sending to the `hello` channel. The message structure is referenced from the hello message component.

Next is the `payload` property under `hello` message component which is used to understand how the event should look like when publishing to that channel:

Expand Down
File renamed without changes
File renamed without changes
30 changes: 17 additions & 13 deletions docs/pages/getting-started/index.md → docs/pages/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,26 +83,29 @@ These scripts refer to the different stages of developing an application.
Create a yaml file that supports capable of receiving a "hello {name}" message with the protocol as `ws` and the channel name as `hello` the hello API will subscribe to. The operationId property is `onHello` that's the name of function and the payload property is type string publishing to that channel.

```yaml
asyncapi: 2.6.0
asyncapi: 3.0.0
info:
title: Hello, Glee!
version: 0.1.0

title: 'Hello, Glee!'
version: 1.0.0
servers:
websockets:
url: ws://0.0.0.0:3000
host: 0.0.0.0:3000
protocol: ws

channels:
hello:
publish:
operationId: onHello
message:
$ref: '#/components/messages/hello'
subscribe:
message:
address: hello
messages:
hello:
$ref: '#/components/messages/hello'

operations:
onHello:
action: receive
channel:
$ref: '#/channels/hello'
sendHello:
action: send
channel:
$ref: '#/channels/hello'
components:
messages:
hello:
Expand All @@ -120,6 +123,7 @@ export default async function (event) {
}]
}
}
```

#### Run the Development Server

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -51,30 +51,43 @@ We recommend creating a new Glee app using our official CLI which sets up everyt

Once the process is completed, you should have a new Glee app ready for development and see these files that were made.

![glee_structure](/assets/glee_struct.png)
![glee_structure](glee_struct.png)

#### Define our Spec for our API

Glee being a spec-first framework, development starts with defining your API spec. To know more details into it, you can follow glee template to understand it step by step. For our case we will define our API:

```yaml
asyncapi: 2.1.0
asyncapi: 3.0.0
info:
title: Greet Bot
version: 0.1.0
version: 1.0.0
servers:
websockets:
url: ws://0.0.0.0:3000
host: 0.0.0.0:3000
protocol: ws
channels:
greet:
publish:
operationId: onGreet
message:
$ref: '#/components/messages/time'
subscribe:
message:
address: greet
messages:
greet:
$ref: '#/components/messages/greet'
time:
$ref: '#/components/messages/time'
time:
address: time
messages:
time:
$ref: '#/components/messages/time'
operations:
onGreet:
action: receive
channel:
$ref: '#/channels/greet'
time.subscribe:
action: send
channel:
$ref: '#/channels/time'
components:
messages:
time:
Expand All @@ -93,7 +106,7 @@ components:

This will be the Specification that defines our API, in our case, it is very simple, as we will be sending a name and the time of the day, and our API will greet us accordingly.

One thing to note here is the `operationId`, this is needed and is a crucial part of glee, as this is how we will be connecting our business logic with our spec, `operationId` is the name of the function that will be called every time a certain operation occurs. In our case whenever `/greet` channel received a message.
One thing to note here is the `operations` item, this is needed and is a crucial part of glee, as this is how we will be connecting our business logic with our spec, `onGreet` is the name of the function that will be called every time a certain operation occurs. In our case whenever `/greet` channel receives a message, `onGreet` function is called.

#### Define our operation function

Expand Down Expand Up @@ -125,10 +138,11 @@ export default async function (event) {

Every file in the functions folder acts as a handler to develop business logic for glee, every file should export an async function that receives an event parameter, where you have access to payload and server details.

Running and testing your application
#### Running and testing your application

We will not execute the application and carry out testing with Postman to ensure that it is functioning as intended.

Now to run your glee application, just run:
Now to execute your glee application, just run:

```
npm run dev
Expand All @@ -137,6 +151,6 @@ npm run start
```
To send a WebSocket request with a payload e.g. `{"name":"john", "time": "1567906535"}` to `ws://localhost:3000/greet`, open Postman and checkout the endpoint:

![glee_response](/assets/glee_resp.png)
![glee_response](glee_resp.png)

So, this is how easy it is to build a WebSocket API using Glee. You can also check out the example code [here](https://github.com/Souvikns/greet-bot).