Building a catalog for Event-Driven Architectures with EventCatalog and AsyncAPI

Introduction

Event Catalog for event-driven architectures is to establish a centralized repository that tracks and manages events in a distributed system. This catalog provides developers, architects, and stakeholders with visibility into event flows between microservices, including the schema for each event and details on which services publish or consume them. This approach enhances communication and understanding across teams, fostering better collaboration and more efficient development processes.

Steps for EventCatalog Implementation

1. Generate an EventCatalog Scaffold project

You can automatically generate an event catalog with EventCatalog by following these steps:

You can create a scaffold project catalog via npx :

npx @eventcatalog/create-eventcatalog@latest my-service-catalog

Once generated, the structure of the Event Catalog project will look like this:

2. Define AsyncAPI Document

For the next step, add the AsyncAPI schema definition to the asyncapi-files folder inside your my-service-catalog project. A complete example of an AsyncAPI document can be found in my previous article Here.

3. Import you AsyncAPI definition into EventCatalog

To integrate the AsyncAPI definition, modify the eventcatalog.config.js file located in the root folder of your project by adding the following:

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

...
export default {
...
  generators: [
    // ASYNCAPI - List of services to add, these are your AsyncAPI files.
    [
      '@eventcatalog/generator-asyncapi',
      {
        services: [{
         path: path.join(__dirname, 'asyncapi-files', 'asyncapi.yaml'), 
         id: 'aircraft-service-asyncapi-2.6.0', 
         name: 'Aircraft Service AsyncAPI 2.6.0', 
         version: '1.0.0' 
        }],
        debug: true
      },
    ],
  ],
};

Pay attention that the id is required

4. Generate EventCatalog with AsyncAPI

To generate the asyncAPI content, first install the generator-asyncapi in your eventcatalog folder :

npm i @eventcatalog/generator-asyncapi

Once installed, you can generate the catalog with the following command:

npm run generate

After generate the import of asyncAPI, you can see that in the events and services folder the information regarding the asyncAPI defintion that we have added by the config.

Now, to visualize your documentation in EventCatalog, run:

npm run dev --host

Navigate to http://localhost:3000/docs to view your Event Catalog documentation.

Conclusion

In conclusion, building an Event Catalog is essential for managing events in event-driven architectures. By clearly defining event schemas and utilizing tools like AsyncAPI or even OpenAPI (not explain in this post), developers can enhance collaboration and streamline communication across microservices. This guide provides a comprehensive approach to creating your Event Catalog, enabling you to improve visibility and organization within your systems. Embrace the power of event-driven design to foster innovation and efficiency in your projects.