Nunjucks render engine

Nunjucks is the default render engine, however, we strongly recommend adopting the React engine.

Common assumptions

1. Templates may contain Nunjucks filters or helper functions. Read more about filters.
2. Templates may contain partials (reusable chunks). They must be stored in the .partials directory under the template directory. Read more about partials.
3. Templates may contain multiple files. Unless stated otherwise, all files will be rendered.
4. The default variables you have access to in any the template file are the following:
   • asyncapi that is a parsed spec file object. Read the API of the Parser to understand what structure you have access to in this parameter.
   • originalAsyncAPI that is an original spec file before it is parsed.
   • params that contain the parameters provided when generating.

Partials

Files from the .partials directory do not end up with other generated files in the target directory. In this directory you should keep reusable templates chunks that you can include in your templates. You can also put there macros to use them in templates, like in below example:

1{# tags.html #}
2{% macro tags(tagList) %}
3<div class="mt-4">
4  {% for tag in tagList %}
5    <span class="bg-grey-dark font-normal text-sm no-underline text-white rounded lowercase mr-2 px-2 py-1" title="{{tag.description()}}">{{tag.name()}}</span>
6  {% endfor %}
7</div>
8{% endmacro %}
9
10{# operations.html #}
11{% from "./tags.html" import tags %}
12{{ tags(operation.tags()) }}

Filters

A filter is a helper function that you can create to perform complex tasks. They are JavaScript files that register one or many Nunjuck filters. The generator parses all the files in the filters directory. Functions exported from these files are registered as filters.

You can use the filter function in your template as in the following example:

const {{ channelName | camelCase }} = '{{ channelName }}';

The generator also supports asynchronous filters. Asynchronous filters receive as the last argument a callback to resume rendering. Asynchronous filters must be annotated with the async keyword. Make sure to call the callback with two arguments: callback(err, res). err can be null. See the following example of how to use asynchronous filters:

1const filter = module.exports;
2
3async function asyncCamelCase(str, callback) {
4  try {
5    const result = // logic for camel casing str
6    callback(null, result);
7  } catch (error) {
8    callback(error);
9  }
10}
11filter.renderAsyncContent = renderAsyncContent;
12
13// using in template
14{{ channelName | asyncCamelCase }}

Unfortunately, if you need to use Promise, filter still must be annotated with the async keyword:

1async function asyncCamelCase(str, callback) {
2  return new Promise((resolve, reject) => {
3    // logic with callback
4  });
5}

In case you have more than one template and want to reuse filters, you can put them in a single library. You can configure such a library in the template configuration under filters property. To learn how to add such filters to configuration read more about the configuration file.

You can also use the official AsyncAPI nunjucks-filters that are by default included in the generator library.