This template generates two resources related to WebSockets:
- Server application with WebSocket endpoint based on Express.js
- Client HTML file with simple scripts that give you a basic API to talk to the server
Other files are for the setup of developer environment, like .editorconfig or .eslint.
Specification requirements
This is a very early version of the template and not all specification features are supported:
Property name
Reason
Fallback
Default
| servers.*.url |
Template doesn't support variables in the server url. |
- |
- |
| bindings |
Template doesn't use websockets bindings. |
- |
- |
| operationId |
Operation ID must be set for every operation to generate proper functions as there is no fallback in place |
- |
- |
WebSocket
This template must be used with the AsyncAPI Generator. You can find all available options here.
# Install the AsyncAPI Generator
npm install -g @asyncapi/generator
# Run generation
ag https://raw.githubusercontent.com/asyncapi/generator/v1.4.0/test/docs/ws.yml @asyncapi/nodejs-ws-template -o output -p server=localhost
##
## Start the server
##
# Go to the generated server
cd output
# Build generated application
npm i
# Start server
npm start
##
## Start the client
##
# From another terminal tab open generated HTML in browser
open output/index.html
# Open developers console and follow instructions from there
# Connect with server
listen('/echo')
# Send example message
send({ greet: 'Hello from client' })
# You should see the sent message in the logs of the previously started server
You can configure this template by passing different parameters in the Generator CLI: -p PARAM1_NAME=PARAM1_VALUE -p PARAM2_NAME=PARAM2_VALUE
Name
Description
Required
Default
Allowed Values
Example
| server |
The server you want to use in the code. |
Yes |
- |
Name of the server from the list of servers under Servers object |
localhost |
Custom hooks that you can disable
The functionality of this template is extended with different hooks that you can disable like this in the Generator CLI: -d HOOK_TYPE1=HOOK_NAME1,HOOK_NAME2 -d HOOK_TYPE2
Type
Name
Description
| generate:after |
createAsyncapiFile |
It creates AsyncAPI file with content of the spec file passed to the generator |
The most straightforward command to use this template is:
ag https://raw.githubusercontent.com/asyncapi/generator/v1.4.0/test/docs/ws.yml @asyncapi/nodejs-ws-template -o output -p server=localhost
For local development, you need different variations of this command. First of all, you need to know about three important CLI flags:
- --debug enables the debug mode in Nunjucks engine what makes filters debugging simpler.
- --watch-template enables a watcher of changes that you make in the template. It regenerates your template whenever it detects a change.
- --install enforces reinstallation of the template.
There are two ways you can work on template development:
- Use global Generator and template from your local sources:
# assumption is that you run this command from the root of your template
ag https://raw.githubusercontent.com/asyncapi/generator/v1.4.0/test/docs/ws.yml ./ -o output
- Use Generator from sources and template also from local sources. This approach enables more debugging options with awesome console.log in the Generator sources or even the Parser located in node_modules of the Generator:
# assumption is that you run this command from the root of your template
# assumption is that generator sources are cloned on the same level as the template
../generator/cli.js https://raw.githubusercontent.com/asyncapi/generator/v1.4.0/test/docs/ws.yml ./ -o output
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!