README.md

⚡️ AsyncAPI generator for EventCatalog

Features: Generate EventCatalogs with your AsyncAPI files, Auto versioning, schema downloads, map to domains, custom AsyncAPI extensions and more...

Read the Docs | Edit the Docs | View Demo

---

Core Features

• 📃 Document domains, services and messages from your AsyncAPI file (example)
• 📊 Visualise your architecture (demo)
• ⭐ Download your AsyncAPI files and message schemas form EventCatalog (e.g Avro, JSON) (demo)
• 💅 Custom MDX components (read more)
• 🗄️ Auto versioning of your domains, services and messages
• ⭐ Document your channels and protocols
• ⭐ Document queries, commands and events with your AsyncAPI file using EventCatalog extensions
• ⭐ Discoverability feature (search, filter and more) (demo)
• ⭐ And much more...

How it works

EventCatalog is technology agnostic, meaning it can integrate with any schemas, specs or brokers.

EventCatalog supports generators. Generators are scripts are run to pre build to generate content in your catalog. Generators can use the EventCatalog SDK.

With this AsyncAPI plugin you can connect your AsyncAPI files to your catalog. This is done by defining your generators in your eventcatlaog.config.js file.

...
generators: [
    [
      '@eventcatalog/generator-asyncapi',
      {
        services: [
          { path: path.join(__dirname, 'asyncapi-files', 'orders-service.asyncapi.yml'), id: 'Orders Service'},
          { path: path.join(__dirname, 'asyncapi-files', 'accounts-service.asyncapi.yml'), id: 'Accounts Service', name: 'Awesome Accounts Service')},
          // Fetch AsyncAPI file from an external URL
          { path: "https://raw.githubusercontent.com/event-catalog/generator-asyncapi/refs/heads/main/src/test/asyncapi-files/simple.asyncapi.yml", id: 'Payment Service', name: 'Payment Service')}
        ],
        domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
      },
    ],
  ],
...

In this example the generator will read the orders-service.asyncapi.yml file and also fetch AsyncAPI files from an external URL and populate services and messages inside your catalog. It will add the services to the domain Orders.

You can see an example in the eventcatalog-asyncapi-example repo

Getting started

Installation and configuration

Make sure you are on the latest version of EventCatalog.

1. Install the package

@eventcatalog/generator-asyncapi

2. Configure your eventcatalog.config.js file (see example)

3. Run the generate command

npm run generate

4. See your new domains, services and messages, run

npm run dev

Found a problem?

Raise a GitHub issue on this project, or contact us on our Discord server.

Running the project locally

1. Clone the repo
2. Install required dependencies pnpm i
3. Run the examples `npx tsx examples/streelights-mqtt/index.ts
4. Run tests pnpm run tests

Commercial Use

This project is governed by a dual-license. To ensure the sustainability of the project, you can freely make use of this software if your projects are Open Source. Otherwise for proprietary systems you must obtain a commercial license.

You can purchase a license or get a free trial at https://eventcatalog.cloud or email us at hello@eventcatalog.dev.