Generator version vs template version

The generator tool generates whatever you want, as long as it can be defined in a template based on the AsyncAPI document. On the other hand, a template is a file or group of files that specify the kind of output you expect from using the generator's features. For example, you may want to use the NodeJS template to generate boilerplate code for your message-based APIs.

Templates are dependent on the generators' features. For example, the template you want to use may be compatible with the latest generator version but incompatible with the previous versions. Check the configuration file or ReadME of the template to see the version of the generator it supports. The generator has an isTemplateCompatible function that checks if the template is compatible with the version of the generator you want to use. If the template isn't compatible, you will see a terminal error output similar to the following:

1
2
Something went wrong:
Error: This template is not compatible with the current version of the generator (${generatorVersion}). This template is compatible with the following version range: ${generator}.`)

Use the following command to check the version of the AsyncAPI CLI you have installed; asyncapi --version

It is better to lock a specific version of the template and the generator if you plan to use the AsyncAPI CLI and a particular template in production. The differences between using the version of the AsyncAPI CLI you have installed and locking a certain version on production are demonstrated in the following code snippets.

Generate HTML with the latest AsyncAPI CLI using the html-template.

1
2
npm install -g @asyncapi/cli
asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template -o ./docs

Generate HTML using a particular version of the AsyncAPI CLI using the html-template.

1
2
npm install -g @asyncapi/cli@0.20.0
asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template@0.7.0 -o ./docs

Before using newer versions of the template, always look at the changelog first. If the generator's features are not important to you, just make sure to use a version compatible with your template.