diff --git a/docs/pages/glee-template.md b/docs/pages/glee-template.md index 5dac9ea6d..5ba33646f 100644 --- a/docs/pages/glee-template.md +++ b/docs/pages/glee-template.md @@ -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. -{`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: @@ -36,8 +39,8 @@ Let's break it down into pieces: {`info: - title: Hello, Glee! - version: 0.1.0`} + title: 'Hello, Glee!' + version: 1.0.0`} The `info` section provides general information about the API, including its title and version. @@ -46,8 +49,8 @@ Moving on, let's talk about the `servers` section. {`servers: - mosquitto: - url: ws://0.0.0.0:3000 + websockets: + host: 0.0.0.0:3000 protocol: ws`} @@ -58,19 +61,25 @@ Now lets move on to the `channels` section. This section is used to describe the {`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'`} -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: diff --git a/assets/glee_resp.png b/docs/pages/glee_resp.png similarity index 100% rename from assets/glee_resp.png rename to docs/pages/glee_resp.png diff --git a/assets/glee_struct.png b/docs/pages/glee_struct.png similarity index 100% rename from assets/glee_struct.png rename to docs/pages/glee_struct.png diff --git a/docs/pages/getting-started/index.md b/docs/pages/index.md similarity index 91% rename from docs/pages/getting-started/index.md rename to docs/pages/index.md index cc7e724be..fd062f103 100644 --- a/docs/pages/getting-started/index.md +++ b/docs/pages/index.md @@ -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: @@ -120,6 +123,7 @@ export default async function (event) { }] } } +``` #### Run the Development Server diff --git a/docs/pages/getting-started/introduction.md b/docs/pages/introduction.md similarity index 88% rename from docs/pages/getting-started/introduction.md rename to docs/pages/introduction.md index 59ed85f73..55bc696e9 100644 --- a/docs/pages/getting-started/introduction.md +++ b/docs/pages/introduction.md @@ -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: @@ -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 @@ -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 @@ -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).