AsyncAPI Logo
On this page

Library API

Found an error? Have a suggestion?Edit this page on GitHub

Reference API documentation for AsyncAPI Generator library.

Generator

Kind: global class

new Generator

Instantiates a new Generator object.

Params

  • templateName String - Name of the template to generate.
  • targetDir String - Path to the directory where the files will be generated.
  • options Object
    • [.templateParams] Object.<string, string> - Optional parameters to pass to the template. Each template define their own params.
    • [.entrypoint] String - Name of the file to use as the entry point for the rendering process. Use in case you want to use only a specific template file. Note: this potentially avoids rendering every file in the template.
    • [.noOverwriteGlobs] Array.<String> - List of globs to skip when regenerating the template.
    • [.disabledHooks] Object.<String, (Boolean|String|Array.<String>)> - Object with hooks to disable. The key is a hook type. If key has "true" value, then the generator skips all hooks from the given type. If the value associated with a key is a string with the name of a single hook, then the generator skips only this single hook name. If the value associated with a key is an array of strings, then the generator skips only hooks from the array.
    • [.output] String = 'fs' - Type of output. Can be either 'fs' (default) or 'string'. Only available when entrypoint is set.
    • [.forceWrite] Boolean = false - Force writing of the generated files to given directory even if it is a git repo with unstaged files or not empty dir. Default is set to false.
    • [.install] Boolean = false - Install the template and its dependencies, even when the template has already been installed.
    • [.debug] Boolean = false - Enable more specific errors in the console. At the moment it only shows specific errors about filters. Keep in mind that as a result errors about template are less descriptive.
    • [.mapBaseUrlToFolder] Object.<String, String> - Optional parameter to map schema references from a base url to a local base folder e.g. url=https://schema.example.com/crm/ folder=./test/docs/ .
    • [.registry] Object - Optional parameter with private registry configuration
      • [.url] String - Parameter to pass npm registry url
      • [.auth] String - Optional parameter to pass npm registry username and password encoded with base64, formatted like username:password value should be encoded
      • [.token] String - Optional parameter to pass npm registry auth token that you can grab from .npmrc file

Example

1const path = require('path');
2const generator = new Generator('@asyncapi/html-template', path.resolve(__dirname, 'example'));

Example (Passing custom params to the template)

1const path = require('path');
2const generator = new Generator('@asyncapi/html-template', path.resolve(__dirname, 'example'), {
3  templateParams: {
4    sidebarOrganization: 'byTags'
5  }
6});
  • generator.registry : Object** : Npm registry information.

Kind: instance property of Generator

  • generator.templateName : String** : Name of the template to generate.

Kind: instance property of Generator

  • generator.targetDir : String** : Path to the directory where the files will be generated.

Kind: instance property of Generator

  • generator.entrypoint : String** : Name of the file to use as the entry point for the rendering process. Use in case you want to use only a specific template file. Note: this potentially avoids rendering every file in the template.

Kind: instance property of Generator

  • generator.noOverwriteGlobs : Array.<String>** : List of globs to skip when regenerating the template.

Kind: instance property of Generator

  • generator.disabledHooks : Object.<String, (Boolean|String|Array.<String>)>** : Object with hooks to disable. The key is a hook type. If key has "true" value, then the generator skips all hooks from the given type. If the value associated with a key is a string with the name of a single hook, then the generator skips only this single hook name. If the value associated with a key is an array of strings, then the generator skips only hooks from the array.

Kind: instance property of Generator

  • generator.output : String** : Type of output. Can be either 'fs' (default) or 'string'. Only available when entrypoint is set.

Kind: instance property of Generator

  • generator.forceWrite : Boolean** : Force writing of the generated files to given directory even if it is a git repo with unstaged files or not empty dir. Default is set to false.

Kind: instance property of Generator

  • generator.debug : Boolean** : Enable more specific errors in the console. At the moment it only shows specific errors about filters. Keep in mind that as a result errors about template are less descriptive.

Kind: instance property of Generator

  • generator.install : Boolean** : Install the template and its dependencies, even when the template has already been installed.

Kind: instance property of Generator

  • generator.templateConfig : Object** : The template configuration.

Kind: instance property of Generator

  • generator.hooks : Object** : Hooks object with hooks functions grouped by the hook type.

Kind: instance property of Generator

  • generator.mapBaseUrlToFolder : Object** : Maps schema URL to folder.

Kind: instance property of Generator

  • generator.templateParams : Object** : The template parameters. The structure for this object is based on each individual template.

Kind: instance property of Generator

generator.generate

Generates files from a given template and an AsyncAPIDocument object.

Kind: instance method of Generator
Returns: Promise.<void> - A Promise that resolves when the generation is completed.
Params

  • asyncapiDocument AsyncAPIDocument | string - AsyncAPIDocument object to use as source.
  • [parseOptions] Object = {} - AsyncAPI Parser parse options. Check out @asyncapi/parser for more information. Remember to use the right options for the right parser depending on the template you are using.

Example

1await generator.generate(myAsyncAPIdocument);
2console.log('Done!');

Example

1generator
2  .generate(myAsyncAPIdocument)
3  .then(() => {
4    console.log('Done!');
5  })
6  .catch(console.error);

Example (Using async/await)

1try {
2  await generator.generate(myAsyncAPIdocument);
3  console.log('Done!');
4} catch (e) {
5  console.error(e);
6}

generator.validateAsyncAPIDocument

Validates the provided AsyncAPI document.

Kind: instance method of Generator
Throws:

  • Error Throws an error if the document is not valid.

Since: 10/9/2023 - 4:26:33 PM
Params

  • asyncapiDocument * - The AsyncAPI document to be validated.
  • generator.setupOutput()** : Sets up the output configuration based on the specified output type.

Kind: instance method of Generator
Throws:

  • Error If 'output' is set to 'string' without providing 'entrypoint'.

Example

1const generator = new Generator();
2await generator.setupOutput();
  • generator.setupFSOutput() ⇒ Promise.<void>** : Sets up the file system (FS) output configuration.

This function creates the target directory if it does not exist and verifies the target directory if forceWrite is not enabled.

Kind: instance method of Generator
Returns: Promise.<void> - A promise that fulfills when the setup is complete.
Throws:

  • Error If verification of the target directory fails and forceWrite is not enabled.
  • generator.setLogLevel() ⇒ void** : Sets the log level based on the debug option.

If the debug option is enabled, the log level is set to 'debug'.

Kind: instance method of Generator

  • generator.installAndSetupTemplate() ⇒ Promise.<{templatePkgName: string, templatePkgPath: string}>** : Installs and sets up the template for code generation.

This function installs the specified template using the provided installation option, sets up the necessary directory paths, loads the template configuration, and returns information about the installed template.

Kind: instance method of Generator
Returns: Promise.<{templatePkgName: string, templatePkgPath: string}> - A promise that resolves to an object containing the name and path of the installed template.

generator.configureTemplateWorkflow

Configures the template workflow based on provided parsing options.

This function performs the following steps:

  1. Parses the input AsyncAPI document using the specified parse options.
  2. Validates the template configuration and parameters.
  3. Configures the template based on the parsed AsyncAPI document.
  4. Registers filters, hooks, and launches the 'generate:before' hook if applicable.

Kind: instance method of Generator
Returns: Promise.<void> - A promise that resolves when the configuration is completed.
Params

  • parseOptions * - Options for parsing the AsyncAPI document.
  • generator.handleEntrypoint() ⇒ Promise.<void>** : Handles the logic for the template entrypoint.

If an entrypoint is specified:

  • Resolves the absolute path of the entrypoint file.
  • Throws an error if the entrypoint file doesn't exist.
  • Generates a file or renders content based on the output type.
  • Launches the 'generate:after' hook if the output is 'fs'.

If no entrypoint is specified, generates the directory structure.

Kind: instance method of Generator
Returns: Promise.<void> - A promise that resolves when the entrypoint logic is completed.

  • generator.executeAfterHook() ⇒ Promise.<void>** : Executes the 'generate:after' hook.

Launches the after-hook to perform additional actions after code generation.

Kind: instance method of Generator
Returns: Promise.<void> - A promise that resolves when the after-hook execution is completed.

  • generator.parseInput()** : Parse the generator input based on the template templateConfig.apiVersion value.

Kind: instance method of Generator

  • generator.configureTemplate()** : Configure the templates based the desired renderer.

Kind: instance method of Generator

generator.generateFromString

Deprecated

Generates files from a given template and AsyncAPI string.

Kind: instance method of Generator
Params

  • asyncapiString String - AsyncAPI string to use as source.
  • [parseOptions] Object = {} - AsyncAPI Parser parse options. Check out @asyncapi/parser for more information.

Example

1const asyncapiString = `
2asyncapi: '2.0.0'
3info:
4  title: Example
5  version: 1.0.0
6...
7`;
8generator
9  .generateFromString(asyncapiString)
10  .then(() => {
11    console.log('Done!');
12  })
13  .catch(console.error);

Example (Using async/await)

1const asyncapiString = `
2asyncapi: '2.0.0'
3info:
4  title: Example
5  version: 1.0.0
6...
7`;
8
9try {
10  await generator.generateFromString(asyncapiString);
11  console.log('Done!');
12} catch (e) {
13  console.error(e);
14}

generator.generateFromURL

Generates files from a given template and AsyncAPI file stored on external server.

Kind: instance method of Generator
Params

  • asyncapiURL String - Link to AsyncAPI file

Example

1generator
2  .generateFromURL('https://example.com/asyncapi.yaml')
3  .then(() => {
4    console.log('Done!');
5  })
6  .catch(console.error);

Example (Using async/await)

1try {
2  await generator.generateFromURL('https://example.com/asyncapi.yaml');
3  console.log('Done!');
4} catch (e) {
5  console.error(e);
6}

generator.generateFromFile

Generates files from a given template and AsyncAPI file.

Kind: instance method of Generator
Params

  • asyncapiFile String - AsyncAPI file to use as source.

Example

1generator
2  .generateFromFile('asyncapi.yaml')
3  .then(() => {
4    console.log('Done!');
5  })
6  .catch(console.error);

Example (Using async/await)

1try {
2  await generator.generateFromFile('asyncapi.yaml');
3  console.log('Done!');
4} catch (e) {
5  console.error(e);
6}

generator.installTemplate

Downloads and installs a template and its dependencies

Kind: instance method of Generator
Params

  • [force] Boolean = false - Whether to force installation (and skip cache) or not.

Generator.getTemplateFile

Returns the content of a given template file.

Kind: static method of Generator
Params

  • templateName String - Name of the template to generate.
  • filePath String - Path to the file to render. Relative to the template directory.
  • [templatesDir] String = DEFAULT_TEMPLATES_DIR - Path to the directory where the templates are installed.

Example

1const Generator = require('@asyncapi/generator');
2const content = await Generator.getTemplateFile('@asyncapi/html-template', 'partials/content.html');

Example (Using a custom `templatesDir`)

1const Generator = require('@asyncapi/generator');
2const content = await Generator.getTemplateFile('@asyncapi/html-template', 'partials/content.html', '~/my-templates');
Was this helpful?
Help us improve the docs by adding your contribution.
OR
Github:AsyncAPICreate Issue on GitHub