There are two ways to use the generator:
AsyncAPI CLI
Generates whatever you want using templates compatible with AsyncAPI Generator.
1USAGE
2 $ asyncapi generate fromTemplate [ASYNCAPI] [TEMPLATE] [-h] [-d <value>] [-i] [--debug] [-n <value>] [-o <value>] [--force-write] [-w] [-p <value>] [--map-base-url <value>]
3
4ARGUMENTS
5 ASYNCAPI - Local path, url or context-name pointing to AsyncAPI file
6 TEMPLATE - Name of the generator template like for example @asyncapi/html-template or https://github.com/asyncapi/html-template
7
8FLAGS
9 -d, --disable-hook=<value>... Disable a specific hook type or hooks from a given hook type
10 -h, --help Show CLI help.
11 -i, --install Installs the template and its dependencies (defaults to false)
12 -n, --no-overwrite=<value>... Glob or path of the file(s) to skip when regenerating
13 -o, --output=<value> Directory where to put the generated files (defaults to current directory)
14 -p, --param=<value>... Additional param to pass to templates
15 -w, --watch Watches the template directory and the AsyncAPI document, and re-generate the files when changes occur. Ignores the output directory.
16 --debug Enable more specific errors in the console
17 --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)
18 --map-base-url=<value> Maps all schema references from base url to local folder
19
20EXAMPLES
21 $ asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template --param version=1.0.0 singleFile=true --output ./docs --force-writeAll templates are installable npm packages. Therefore, the value of template can be anything supported by npm install. Here's a summary of the possibilities:
1npm install [<@scope>/]<name>
2npm install [<@scope>/]<name>@<tag>
3npm install [<@scope>/]<name>@<version>
4npm install [<@scope>/]<name>@<version range>
5npm install <git-host>:<git-user>/<repo-name>
6npm install <git repo url>
7npm install <tarball file>
8npm install <tarball url>
9npm install <folder>Global templates installed with yarn or npm
You can preinstall templates globally before installing the AsyncAPI CLI. The generator first tries to locate the template in local dependencies; if absent it checks where the global generator packages are installed.
1npm install -g @asyncapi/html-template@0.16.0
2asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template
3# The generator uses html-template version 0.16.0 and not the latest version.CLI usage examples
The shortest possible syntax:
asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-templateGenerating from a URL:
asyncapi generate fromTemplate https://bit.ly/asyncapi @asyncapi/html-templateSpecify where to put the result:
asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template -o ./docsPassing parameters to templates:
asyncapi generate fromTemplate 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:
asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template -o ./docs -d generate:before generate:after=foo,barThe generator skips all hooks of the generate:before type and foo, bar hooks of the generate:after type.
Installing the template from a folder:
asyncapi generate fromTemplate asyncapi.yaml ~/my-templateIt creates a symbolic link to the target directory (~/my-template in this case).
Installing the template from a git URL:
asyncapi generate fromTemplate asyncapi.yaml https://github.com/asyncapi/html-template.gitMap schema references from baseUrl to local folder:
asyncapi generate fromTemplate 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.
CLI usage with Docker
When using our docker image that we regularly update, you don't need to install Node.js or Npm, even though the generator is written with it since the Docker image has the generator installed.
Install Docker first, then use docker to pull and run the image using the following command:
1docker run --rm -it \
2-v [ASYNCAPI SPEC FILE LOCATION]:/app/asyncapi.yml \
3-v [GENERATED FILES LOCATION]:/app/output \
4asyncapi/cli [COMMAND HERE]
5
6# Example that you can run inside the cli directory after cloning this repository. First, you specify the mount in the location of your AsyncAPI specification file and then you mount it in the directory where the generation result should be saved.
7docker run --rm -it \
8 -v ${PWD}/test/fixtures/asyncapi_v1.yml:/app/asyncapi.yml \
9 -v ${PWD}/output:/app/output \
10 asyncapi/cli generate fromTemplate -o /app/output /app/asyncapi.yml @asyncapi/html-template --force-writeNote: Use ` instead of \ for Windows.
CLI usage with npx instead of npm
npx is very useful when you want to run the generator in a CI/CD environment. In such a scenario, do not install the generator globally because most environments that provide Node.js and Npm, also provide npx out of the box.
Use the following npx command on your terminal:
npx -p @asyncapi/cli asyncapi generate fromTemplate ./asyncapi.yaml @asyncapi/html-templateUsing as a module/package
Once you install the generator in your project, you can use it to generate whatever you want. The following code snippet is an example of HTML generation using the official @asyncapi/html-template template and fetching the spec document from the server using:
https://raw.githubusercontent.com/asyncapi/asyncapi/2.0.0/examples/2.0.0/streetlights.yml1const path = require('path');
2const generator = new Generator('@asyncapi/html-template', path.resolve(__dirname, 'example'));
3
4try {
5 await generator.generateFromURL('https://raw.githubusercontent.com/asyncapi/asyncapi/2.0.0/examples/2.0.0/streetlights.yml');
6 console.log('Done!');
7} catch (e) {
8 console.error(e);
9}See the API documentation for more examples and full API reference information.
