Skip to main content

Introduction

Added in eventcatalog@2.5.0
License: Dual-license

Many folks building event-driven architectures are using and defining AsyncAPI files. The files are used to describe the service, it's messages it sends and receives and channels it uses to communicate.

Using the EventCatalog AsyncAPI generator you can generate and maintain your EventCatalog.

info

What is AsyncAPI?: An industry standard for defining asynchronous APIs. Use this specification to document your service, channels and messages.

Core Features​

The EventCatalog AsyncAPI plugin can provide you with many features:

How it works​

Example

EventCatalog supports generators. These are scripts or plugins that can be run to integrate with any external API, system or specification files. EventCatalog also provides an SDK to give developers easier access to their catalogs through custom scripts or generators.

The EventCatalog AsyncAPI plugin let's you define 1 or many AsyncAPI files. When running the generate command the scripts populate your eventcatalog. You can choose how your AsyncAPI services are added to EventCatalog and which domain they belong to.

Getting started​

1. Install the plugin​

npm i @eventcatalog/generator-asyncapi

2. Configure your generator in your 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',
  // By default set to false, add true to get urls ending in /
  trailingSlash: false,
  // Change to make the base url of the site different, by default https://{website}.com/docs,
  // changing to /company would be https://{website}.com/company/docs,
  base: '/',
  // Customize the logo, add your logo to public/ folder
  logo: {
    alt: 'EventCatalog Logo',
    src: '/logo.png',
    text: 'OurLogix',
  },
  docs: {
    sidebar: {
      // Should the sub heading be rendered in the 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'), id: "Orders Service"}
        ],
        domain: { id: 'orders', name: 'Orders', version: '0.0.1' },

        // Run in debug mode, for extra output, if your AsyncAPI fails to parse, it will tell you why
        debug: true
      },
    ],
    // Add many AsyncAPI files to a domain
    [
      '@eventcatalog/generator-asyncapi',
      {
        services: [
          // Add AsyncAPI file by URL
          { path: "https://raw.githubusercontent.com/event-catalog/eventcatalog-asyncapi-example/refs/heads/main/asyncapi-files/payment-service.yml", id: "Payment Service"}
          // Add AsyncAPI file using file system
          { path: path.join(__dirname, 'asyncapi-files', 'fraud-detection-service.yml'), "Fraud Service"}
        ],
        domain: { id: 'payment', name: 'Payment', version: '0.0.1' },
        // Run in debug mode, for extra output, if your AsyncAPI fails to parse, it will tell you why
        debug: true
      },
    ],
  ],
};

3. Run the generate command​

This command will run the generators in your eventcatalog.config.js file.

npm run generate

4. View your catalog​

Run your catalog locally to see the changes

npm run dev

Commercial Use​

This plugin is governed by a dual-license. To ensure the sustainability of the project, you can freely make use of this software if usage is also Open Source. Otherwise for proprietary use, internal use, and private modifications you must obtain a commercial license.

To purchase a license you to login to the EventCatalog Dashboard or if you have any questions you you can email us at hello@eventcatalog.dev.

Login to EventCatalog Dashboard

Features​

Mapping messages events, commands or queries​

AsyncAPI does not distinguish between commands, events and queries, everything is a message.

Using the EventCatalog custom AsyncAPI extension x-eventcatalog-message-type you can specify if your messages are events, command or queries.

You can use the x-eventcatalog-message-type to specify the type of message.

By default everything parsed by EventCatalog is an event, unless you specify with the x-eventcatalog-message-type extension.

x-eventcatalog-message-type example
components:
  messages:
    OrderCreated:
      description: 'Event triggered when an order is created'
      x-eventcatalog-message-type: event // event/query/command

You can see more examples of the extension on the demo project.

Persist markdown​

When you generate your AsyncAPI files your markdown on your domains,services, and messages in EventCatalog is persisted between versions.

This allows you to add custom components, our MDX components and customize your EventCatalog pages without losing changes when you version your AsyncAPI files.

Fetch AsyncAPI files by URL​

Added in @eventcatalog/generator-asyncapi@2.3.0

You can use the path property of the generator to specify a path to your local file system or an external URL, or you can mix both of them.

[
    '@eventcatalog/generator-asyncapi',
    {
      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 AsyncAPI file using file system
        { path: path.join(__dirname, 'asyncapi-files', 'fraud-detection-service.yml'), "Fraud Service"}
      ],
      domain: { id: 'payment', name: 'Payment', version: '0.0.1' },
      // Run in debug mode, for extra output, if your AsyncAPI fails to parse, it will tell you why
      debug: true
    },
  ],

Automatic versioning​

When you change versions in your AsyncAPI file and run generate, your services and messages are automatically versioned. This allows you to keep an audit log of changes between AsyncAPI files, schemas and more.

You can also add changelogs between different versions of your services and messages. Read here for more information.

Downloading schemas​

If your messages have schemas (e.g avro, json) EventCatalog will document these for you. Run your generator and every message will show it's schema on the UI and give users the ability to download it's schema.

The service that is also generated will allow you to see and download the AsyncAPI file.

Example​

See the eventcatalog-asyncapi-example for a working example.