Skip to main content

Workflows

There are a few ways to configure the AsyncAPI plugin depending on your preferred development workflows. Many companies have different needs, so we have provided a few different workflows to choose from.

If we are missing a workflow that you think is useful, please raise an issue on GitHub.

Simple mapping between AsyncAPI files and EventCatalog services​

This is the simplest workflow and is useful if you have a single AsyncAPI file per service.

EventCatalog will parse your AsyncAPI file and map it's specification to the service you define.

This will document your service, and the messages it produces and consumes.

eventcatalog.config.js
// ...rest of file
generators: [
  [
    '@eventcatalog/generator-asyncapi',
    {
      services: [
        // Tell EventCatalog where the AsyncAPI file is located and map it to the service you define
        { path: path.join(__dirname, 'asyncapi-files', 'orders-service.yml'), id: 'orders-service' },
      ],
    },
  ],
],

Independent message versions from your AsyncAPI file​

This is useful if you want to version your messages separately from the AsyncAPI file.

AsyncAPI currently does not support versioning messages separately from the AsyncAPI file, that's why you have to use the x-eventcatalog-message-version extension.

You can use the x-eventcatalog-message-version extension to specify a different version for a particular message.

asyncapi: 3.0.0
info:
  title: Orders Service
  version: 1.0.0
components:
  messages:
    OrderCreated:
      description: 'Event triggered when an order is created'
      # Specify the version of the message to 2.0.0
      x-eventcatalog-message-version: 2.0.0
      payload:
        type: object
        properties:
          orderId:
            type: string
            description: The ID of the order

In the example above, the message OrderCreated will be versioned as 2.0.0 and all other messages will be versioned as 1.0.0.

You can read more about message versioning in the Features section.

Mapping multiple AsyncAPI files to a single EventCatalog service​

This is useful if you have a single service that produces and consumes multiple AsyncAPI versions.

Some people call this a "polyglot" service, as it produces and consumes multiple APIs.

eventcatalog.config.js
// ...rest of file
generators: [
  [
    '@eventcatalog/generator-asyncapi',
    {
      services: [
        // Version 1 of the AsyncAPI file
        { path: path.join(__dirname, 'asyncapi-files', 'orders-service-v1.yml'), id: 'orders-service' },
        // Version 2 of the AsyncAPI File
        { path: path.join(__dirname, 'asyncapi-files', 'orders-service-v2.yml'), id: 'orders-service' },
      ],
    },
  ],
],
Versioning

When you map multiple versions of an AsyncAPI file to a single service, the version property in your AsyncAPI files needs to be the same.

If they are different, EventCatalog will version the previous versions of your service.

In the example above, the version property in the AsyncAPI files is 1.0.0 and 2.0.0.

EventCatalog will version the service as 1.0.0 and 2.0.0.

The messages in the service will be versioned as 1.0.0 and 2.0.0.

This allows you to track the history of your service and the messages in it.

Mapping AsyncAPI and OpenAPI files to the same EventCatalog service​

Added in @eventcatalog/generator-asyncapi@5.1.1
Added in @eventcatalog/generator-openapi@7.6.1

This is useful if you have a single service that produces and consumes both AsyncAPI and OpenAPI files.

In this example we map an OpenAPI file and an AsyncAPI file to the same service (inventory-service).

The AsyncAPI and OpenAPI may have their own versions independent of each other, but EventCatalog will document both of them in the same service.

Message Versioning

You can still use the x-eventcatalog-message-version extension to version your messages independently of the service version.

eventcatalog.config.js
// ...rest of file
generators: [
    [
      "@eventcatalog/generator-openapi",
      {
        services: [
          { path: path.join(__dirname, "specifications", "openapi.yml"), id: "inventory-service", version: "15.2.0" },
        ],
      },
    ],
    [
      "@eventcatalog/generator-asyncapi",
      {
        services: [{ path: path.join(__dirname, "specifications", "asyncapi.yml"), id: "inventory-service", version: "15.2.0" }],
      },
    ],
  ],