Generator API

Overview

API for the EventCatalog AsyncAPI generator.

Example eventcatalog.config.js file

eventcatalog.config.js

---
import path from 'path';
import url from 'url';

const __dirname = path.dirname(url.fileURLToPath(import.meta.url));

/** @type {import('@eventcatalog/core/bin/eventcatalog.config').Config} */
export default {
  title: 'OurLogix',
  tagline: 'A comprehensive logistics and shipping management company',
  organizationName: 'OurLogix',
  homepageLink: 'https://eventcatalog.dev/',
  landingPage: '',
  editUrl: 'https://github.com/boyney123/eventcatalog-demo/edit/master',
  trailingSlash: false,
  base: '/',
  logo: {
    alt: 'EventCatalog Logo',
    src: '/logo.png',
    text: 'OurLogix',
  },
  docs: {
    sidebar: {
      showPageHeadings: true,
    },
  },
  generators: [
    // Add single AsyncAPI file to a domain
    [
      '@eventcatalog/generator-asyncapi',
      {
        services: [
          { path: path.join(__dirname, 'asyncapi-files', 'orders-service.yml')}
        ],
        domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
      },
    ],
    // Add many AsyncAPI files to a domain
    [
      '@eventcatalog/generator-asyncapi',
      {
        services: [
          { path: path.join(__dirname, 'asyncapi-files', 'payment-service.yml')}
          { path: path.join(__dirname, 'asyncapi-files', 'fraud-detection-service.yml')}
        ],
        domain: { id: 'payment', name: 'Payment', version: '0.0.1' },
      },
    ],
  ],
};

warning

When importing node modules into your eventcatalog.config.js file, you need to import the entire package.

import path from 'path'; //work

import { join } from 'path'; // will not work

This is currently a limitation and is being looked at. Any problems or issues feel free to raise a GitHub issue.

Required fields

services

• Type: Service[]

List of services to add, these are your AsyncAPI files.

eventcatalog.config.js

[
    '@eventcatalog/generator-asyncapi',
    {
        // Just one AsyncAPI file
        services: [
          { path: path.join(__dirname, 'asyncapi-files', 'orders-service.yml'), id: 'order-service'}
        ],
        domain: { id: 'payment', name: 'Payment', version: '0.0.1' },
    },
    '@eventcatalog/generator-asyncapi',
    {
        // Many AsyncAPI files
        services: [
           // Add AsyncAPI file by public URL
          { path: "https://raw.githubusercontent.com/event-catalog/eventcatalog-asyncapi-example/refs/heads/main/asyncapi-files/payment-service.yml", id: "Payment Service"},
          // Add by file system
          { path: path.join(__dirname, 'asyncapi-files', 'fraud-detection-service.yml'), id: 'fraud-detection-service'}
        ],
        domain: { id: 'payment', name: 'Payment', version: '0.0.1' },
    },
]

Service properties

Property name	Required	Description
path	true	The path to your AsyncAPI file (file system path, or URL)
id	true	Id of the service, this will also be used as the folder name of your service.
name	optional	Name of your service. This is optional if you want to give your service a name (rendered in EventCatalog). Defaults to the title value in your AsyncAPI document

Optional fields

domain

The domain you want the AsyncAPI file/s to be associated with in your catalog.

eventcatalog.config.js

[
    '@eventcatalog/generator-asyncapi',
    {
        // No domain
        services: [
          { path: path.join(__dirname, 'asyncapi-files', 'orders-service.yml'), id: 'order-service'}
        ]
    },
    '@eventcatalog/generator-asyncapi',
    {
        services: [
          { path: path.join(__dirname, 'asyncapi-files', 'payment-service.yml'), id: 'payment-service'}
          { path: path.join(__dirname, 'asyncapi-files', 'fraud-detection-service.yml'), id: 'fraud-detection-service'}
        ],
        // Add to the payment domain
        domain: { id: 'payment', name: 'Payment', version: '0.0.1' },
    },
]

saveParsedSpecFile

Added in @eventcatalog/generator-asyncapi@2.0.0

By default your AsyncAPI file will render in your catalog as you define it.

If you are using $refs, or having issues seeing your AsyncAPI file in your catalog, then you can set this value to true.

saveParsedSpecFile is false by default.

Setting saveParsedSpecFile to true will use the AsyncAPI parser under the hood to parse your Spec file. This parsed spec file will be written to your catalog. Read https://www.asyncapi.com/docs/tools/generator/parser for more information.

eventcatalog.config.js

[
    '@eventcatalog/generator-asyncapi',
    {
        // No domain
        services: [
          { path: path.join(__dirname, 'asyncapi-files', 'orders-service.yml'), id: 'orders-service'}
        ],
        saveParsedSpecFile: true
    },
    '@eventcatalog/generator-asyncapi',
    {
        services: [
          { path: path.join(__dirname, 'asyncapi-files', 'payment-service.yml'), id: 'payment-service'}
          { path: path.join(__dirname, 'asyncapi-files', 'fraud-detection-service.yml'), id: 'fraud-detection-service'}
        ],
        saveParsedSpecFile: true,
        // Add to the payment domain
        domain: { id: 'payment', name: 'Payment', version: '0.0.1' },
    },
]

parseChannels

Added in @eventcatalog/generator-asyncapi@2.7.0

EventCatalog supports channels as a resource type.

AsyncAPI lets you document your channels, messages that use the channel and the protocol they use.

Setting parseChannels in your generator configuration file, will generate Channel resources into your EventCatalog, and link your messages to these channels.

saveParsedSpecFile is false by default.

eventcatalog.config.js

[
    '@eventcatalog/generator-asyncapi',
    {
        services: [
          { path: path.join(__dirname, 'asyncapi-files', 'orders-service.yml'), id: 'orders-service'}
        ],
        // Try and parse the channels and add them to EventCatalog
        parseChannels: true
    }]

parseSchemas

Added in @eventcatalog/generator-asyncapi@2.5.1

If you choose to parse your specification file using the saveParsedSpecFile field, you can also opt in or out to have your ,message schemas parsed using the parseSchemas field.

By default message schemas are parsed, if you want to keep your original schemas you have to set parseSchemas to false.

Parsed schemas (true) (default)

• Message schemas are validated
• Message schemas are converted into JSON schemas
• AsyncAPI parser metadata (e.g x-parser-schema-id) is added to your schemas

Parsed schemas (false) (default)

• Does not validate your schemas
• Keeps original message schema formats unchanged
• Does not add any schema-related metadata

eventcatalog.config.js

[
    '@eventcatalog/generator-asyncapi',
    {
        // No domain
        services: [
          { path: path.join(__dirname, 'asyncapi-files', 'orders-service.yml'), id: 'orders-service'}
        ],
        saveParsedSpecFile: true,
        // Keep the message schemas as they are, do not add metadata onto them
        parseSchemas: false
    },
    '@eventcatalog/generator-asyncapi',
    {
        services: [
          { path: path.join(__dirname, 'asyncapi-files', 'payment-service.yml'), id: 'payment-service'}
          { path: path.join(__dirname, 'asyncapi-files', 'fraud-detection-service.yml'), id: 'fraud-detection-service'}
        ],
        saveParsedSpecFile: true,
        // Parse the message schemas, transform them to JSON schemas and add metadata info onto them (default)
        parseSchemas: true
        // Add to the payment domain
        domain: { id: 'payment', name: 'Payment', version: '0.0.1' },
    },
]

If you are having issues with the AsyncAPI renderer in EventCatalog you may also want to set the parseSchemas flag for the HTML renderer in your eventcatalog.config.js file. Learn more.

debug

Debug flag that will log extra information. For example if your AsyncAPI file fails to parse, it will tell you why.

eventcatalog.config.js

[
    '@eventcatalog/generator-asyncapi',
    {
        // No domain
        services: [
          { path: path.join(__dirname, 'asyncapi-files', 'orders-service.yml'), id: 'orders-service'}
        ]
    },
    '@eventcatalog/generator-asyncapi',
    {
        services: [
          { path: path.join(__dirname, 'asyncapi-files', 'payment-service.yml'), id: 'payment-service'}
          { path: path.join(__dirname, 'asyncapi-files', 'fraud-detection-service.yml'), id: 'fraud-detection-service'}
        ],
        // Add to the payment domain
        domain: { id: 'payment', name: 'Payment', version: '0.0.1' },

        //debug flag
        debug: true
    },
]

Upgrading to 2.0 generator

• folderName is no longer used from version 2.0. Please use id in the service.
• id is now required in the Service configuration