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: [
          { 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'}
        ],
        domain: { id: 'payment', name: 'Payment', version: '0.0.1' },
    },
]

Service properties

Property name	Required	Description
path	true	The path to your AsyncAPI file
id	required	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' },
    },
]

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