@asyncapi/generator

AsyncAPI Generator

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.

Requirements

• Node.js v12.16+
• npm v6.13.7+

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

Install

npm install -g @asyncapi/generator

Or just use Docker:

docker run --rm -it \
-v [ASYNCAPI 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 file and then you mount in directory where generation result should be saved.
docker run --rm -it \
-v ${PWD}/test/docs/streetlights.yml:/app/asyncapi.yml \
-v ${PWD}/output:/app/output \
asyncapi/generator -o ./output asyncapi.yml @asyncapi/html-template --force-write

Usage

From the command-line interface (CLI)

Usage: cli [options] <asyncapi> <template>

Options:
  -V, --version                  output the version number
  -d, --disable-hook <hookName>  disable a specific hook
  -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
  -h, --help                     output usage information

Click here to read more about supported values for the <template> parameter.

Templates are installable npm packages. Therefore, the value of <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>

:mag: Do you want to find a template? Click here!

Examples

The shortest possible syntax:

ag asyncapi.yaml @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 }}

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

As a module

See API documentation.

Authoring templates

See authoring templates and the list of templates recipes.

Contributing

Read CONTRIBUTING guide.

Author

Fran Méndez (@fmvilas)