Research
Security News
Quasar RAT Disguised as an npm Package for Detecting Vulnerabilities in Ethereum Smart Contracts
Socket researchers uncover a malicious npm package posing as a tool for detecting vulnerabilities in Etherium smart contracts.
@asyncapi/generator
Advanced tools
The AsyncAPI generator. It can generate documentation, code, anything!
Use your AsyncAPI definition to generate literally anything. Markdown documentation, Node.js code, HTML documentation, anything!
:warning: This package doesn't support AsyncAPI 1.x anymore. We recommend to upgrade to the latest AsyncAPI version using the AsyncAPI converter. If you need to convert documents on the fly, you may use the Node.js or Go converters.
Generator is a tool that you can use to generate whatever you want basing on the AsyncAPI specification file as an input.
To specify what exactly must be generated you create so called template. To create your own template, go to section that explains How to create a template.
There is a large number of templates that are ready to use and are officially supported by the AsyncAPI Initiative.
Template Name | Description | Source code |
---|---|---|
@asyncapi/nodejs-template | Generates Nodejs service that uses Hermes package | click here |
@asyncapi/nodejs-ws-template | Generates Nodejs service that supports WebSockets protocol only | click here |
@asyncapi/java-spring-template | Generates Java Spring service | click here |
@asyncapi/java-spring-cloud-stream-template | Generates Java Spring Cloud Stream service | click here |
@asyncapi/python-paho-template | Generates Python service that uses Paho library | click here |
@asyncapi/html-template | Generates HTML documentation site | click here |
@asyncapi/markdown-template | Generates documentation in Markdown file | click here |
@asyncapi/ts-nats-template | Generates TypeScript NATS client | click here |
You can find above templates and the ones provided by the community in this list
Install both packages using official installer. After installation make sure both packages have proper version by running node -v
and npm -v
. To upgrade invalid npm version run npm install npm@latest -g
Generator is tested at the moment against Node 14 and NPM 6. Using newer versions is enabled but we do not guarantee they work well. Please provide feedback on the issues.
To use it as CLI, install generator globally:
npm install -g @asyncapi/generator
You might want to update your local installation of generator for different reasons:
npm install -g @asyncapi/generator
@
character:
npm install -g @asyncapi/generator@0.50.0
Sometimes you have to force additional npm installation like this:
npm install -g --force @asyncapi/generator
Usage: ag [options] <asyncapi> <template>
- <asyncapi>: Local path or URL pointing to AsyncAPI specification file
- <template>: Name of the generator template like for example @asyncapi/html-template or https://github.com/asyncapi/html-template
Options:
-V, --version output the version number
-d, --disable-hook [hooks...] disable a specific hook type or hooks from given hook type
--debug enable more specific errors in the console
-i, --install installs the template and its dependencies (defaults to false)
-n, --no-overwrite <glob> glob or path of the file(s) to skip when regenerating
-o, --output <outputDir> directory where to put the generated files (defaults to current directory)
-p, --param <name=value> additional param to pass to templates
--force-write force writing of the generated files to given directory even if it is a git repo with unstaged files or not empty dir (defaults to false)
--watch-template watches the template directory and the AsyncAPI document, and re-generate the files when changes occur. Ignores the output directory. This flag should be used only for template development.
--map-base-url <url:folder> maps all schema references from base url to local folder
-h, --help display help for command
<template>
parameter.<template>
can be anything supported by npm install
. Here's a summary of the possibilities:
npm install [<@scope>/]<name>
npm install [<@scope>/]<name>@<tag>
npm install [<@scope>/]<name>@<version>
npm install [<@scope>/]<name>@<version range>
npm install <git-host>:<git-user>/<repo-name>
npm install <git repo url>
npm install <tarball file>
npm install <tarball url>
npm install <folder>
You can preinstall templates globally. The generator first tries to locate template in local dependencies and then in location where global packages are installed.
npm install -g @asyncapi/html-template@0.16.0
ag asyncapi.yaml @asyncapi/html-template
# The generator uses template in version 0.16.0 and not latest
The shortest possible syntax:
ag asyncapi.yaml @asyncapi/html-template
Generating from a URL:
ag https://bit.ly/asyncapi @asyncapi/html-template
Specify where to put the result:
ag asyncapi.yaml @asyncapi/html-template -o ./docs
Passing parameters to templates:
ag asyncapi.yaml @asyncapi/html-template -o ./docs -p title='Hello from param'
In the template you can use it like this: {{ params.title }}
Disabling the hooks:
ag asyncapi.yaml @asyncapi/html-template -o ./docs -d generate:before generate:after=foo,bar
The generator skips all hooks of the generate:before
type and foo
, bar
hooks of the generate:after
type.
Installing the template from a folder:
ag asyncapi.yaml ~/my-template
It creates a symbolic link to the target directory (~/my-template
in this case).
Installing the template from a git URL:
ag asyncapi.yaml https://github.com/asyncapi/html-template.git
Map schema references from baseUrl to local folder:
ag test/docs/apiwithref.json @asyncapi/html-template -o ./build/ --force-write --map-base-url https://schema.example.com/crm/:./test/docs/
The parameter --map-base-url
maps external schema references to local folders.
Install Docker first. Thanks to Docker you do not need Node.js even though the generator is written with it.
docker run --rm -it \
-v [ASYNCAPI SPEC FILE LOCATION]:/app/asyncapi.yml \
-v [GENERATED FILES LOCATION]:/app/output \
asyncapi/generator [COMMAND HERE]
# Example that you can run inside generator directory after cloning this repository. First you specify mount in location of your AsyncAPI specification file and then you mount in directory where generation result should be saved.
docker run --rm -it \
-v ${PWD}/test/docs/dummy.yml:/app/asyncapi.yml \
-v ${PWD}/output:/app/output \
asyncapi/generator -o /app/output /app/asyncapi.yml @asyncapi/html-template --force-write
The npx is very useful when you want to run Generator in CI/CD environment. In such a scenario, you do not want to install generator globally and most environments that provide Node.js and npm, also provide npx out of the box.
npx -p @asyncapi/generator ag ./asyncapi.yaml @asyncapi/html-template
npm install @asyncapi/generator --save
Below you can find an example of HTML generation using official @asyncapi/html-template
template and fetching the spec document from server like https://raw.githubusercontent.com/asyncapi/asyncapi/2.0.0/examples/2.0.0/streetlights.yml
:
const path = require('path');
const generator = new Generator('@asyncapi/html-template', path.resolve(__dirname, 'example'));
try {
await generator.generateFromURL('https://raw.githubusercontent.com/asyncapi/asyncapi/2.0.0/examples/2.0.0/streetlights.yml');
console.log('Done!');
} catch (e) {
console.error(e);
}
See API documentation for more example and full API reference information.
The Generator is a tool that you can use to generate whatever you want, taking an AsyncAPI specification file as the input. A template is a tool that uses Generator features and helpers to specify what should be generated.
In other words, a template depends on the Generator and its features. For example, it might work with the latest version of the Generator but not the previous ones.
The owner of the template specifies in the configuration what version of the Generator it is compatible with:
"generator": ">=0.50.0 <2.0.0",
The Generator doesn't work in case the template is not compatible:
Something went wrong:
Error: This template is not compatible with the current version of the generator (0.50.0). This template is compatible with the following version range: >=0.60.0 <2.0.0.
at Generator.validateTemplateConfig (/Users/wookiee/.nvm/versions/node/v12.16.1/lib/node_modules/@asyncapi/generator/lib/generator.js:678:13)
at Generator.loadTemplateConfig (/Users/wookiee/.nvm/versions/node/v12.16.1/lib/node_modules/@asyncapi/generator/lib/generator.js:663:16)
at Generator.generate (/Users/wookiee/.nvm/versions/node/v12.16.1/lib/node_modules/@asyncapi/generator/lib/generator.js:146:18)
at processTicksAndRejections (internal/process/task_queues.js:97:5)
at async /Users/wookiee/.nvm/versions/node/v12.16.1/lib/node_modules/@asyncapi/generator/cli.js:135:7
In case you use Generator CLI and a specific template on production, it is safer to lock to a specific version of the template and the Generator.
Instead of generating HTML with latest html-template
and the generator CLI:
npm install -g @asyncapi/generator
ag asyncapi.yaml @asyncapi/html-template -o ./docs
Generate HTML with the version of the html-template
and the Generator CLI that you are happy with:
npm install -g @asyncapi/generator@0.50.0
ag asyncapi.yaml @asyncapi/html-template@0.7.0 -o ./docs
Before using newer versions of the template, always look at the changelog first. Generator features are not important for you, just make sure to use a version compatible with the template.
To create your own template, for example code generator for some specific language and technology, learn from the following resources:
Read CONTRIBUTING guide.
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!
FAQs
The AsyncAPI generator. It can generate documentation, code, anything!
We found that @asyncapi/generator demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago.ย It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket researchers uncover a malicious npm package posing as a tool for detecting vulnerabilities in Etherium smart contracts.
Security News
Research
A supply chain attack on Rspack's npm packages injected cryptomining malware, potentially impacting thousands of developers.
Research
Security News
Socket researchers discovered a malware campaign on npm delivering the Skuld infostealer via typosquatted packages, exposing sensitive data.