Plugin Configuration

Overview

The EventCatalog Apicurio Registry plugin is configured in the eventcatalog.config.js file inside the generators array.

Authentication

If your Apicurio Registry requires authentication, you can configure a Bearer token as an environment variable.

Example .env file

export APICURIO_ACCESS_TOKEN=your-access-token-here

Required Configuration Options

Option	Type	Required	Description
`registryUrl`	`string`	Yes	The URL of your Apicurio Registry (e.g., `http://localhost:8080`). The plugin automatically appends the `/apis/registry/v3` API path.
`includeAllVersions`	`boolean`	No	If true, all versions of the schemas will be imported into EventCatalog (default is `false`). When enabled, each version of a schema creates a separate versioned entry in EventCatalog.

Optional Configuration Options

Services

You can assign schemas to services (producers/consumers).

Option	Type	Default	Description
`services`	object	-	List of services to assign the schemas to.
`services.id`	string	-	EventCatalog ID for the service.
`services.version`	string	-	Version of the service.
`services.name`	string	-	Name of the service (optional, defaults to ID).
`services.summary`	string	-	Summary description of the service (optional).
`services.sends`	Filter	-	Configuration to assign schemas that this service sends (publishes).
`services.receives`	Filter	-	Configuration to assign schemas that this service receives (consumes).
`services.writesTo`	array	-	Array of services this service writes to. Each entry has `id` (required) and optional `version`.
`services.readsFrom`	array	-	Array of services this service reads from. Each entry has `id` (required) and optional `version`.
`services.specifications`	array	-	Array of specification artifacts (OpenAPI/AsyncAPI) to attach to the service. See Specifications section below.

Domains

You can define and assign domains to your services.

Option	Type	Default	Description
`domain.id`	string	-	EventCatalog ID for the domain (e.g `orders`).
`domain.name`	string	-	Name of the domain (e.g `Orders`).
`domain.version`	string	-	Version of the domain (e.g `1.0.0`).
`domain.summary`	string	-	Summary description of the domain (optional).

Specifications

You can attach OpenAPI or AsyncAPI specifications stored in your Apicurio Registry to services. When configured with a generator, these specifications will be automatically processed to generate comprehensive service documentation including REST endpoints, async events, and more.

Learn more about attaching OpenAPI and AsyncAPI specifications

You can attach OpenAPI or AsyncAPI specifications from your Apicurio Registry to services. These specifications can optionally be processed by their respective EventCatalog plugins to generate additional documentation.

Plugin Licenses Required

The OpenAPI and AsyncAPI generators are separate licensed plugins. To use them with the Apicurio plugin, you'll need to:

Install the respective plugins: npm install @eventcatalog/generator-openapi @eventcatalog/generator-asyncapi
Obtain license keys from EventCatalog Cloud (14-day free trial available)
Configure the license keys in your .env file:
- EVENTCATALOG_LICENSE_KEY_OPENAPI=your-openapi-license-key
- EVENTCATALOG_LICENSE_KEY_ASYNCAPI=your-asyncapi-license-key

Learn more: OpenAPI Plugin Docs | AsyncAPI Plugin Docs

Option	Type	Required	Description
`services.specifications`	array	No	Array of specification configurations to attach to the service.
`specifications[].type`	string	Yes	Type of specification: `'openapi'` or `'asyncapi'`.
`specifications[].artifactId`	string	Yes	The artifact ID in Apicurio Registry.
`specifications[].version`	string	No	Specific version to fetch, or `'latest'` (default).
`specifications[].generator`	array	No	Optional EventCatalog generator to process the specification. Format: `['@eventcatalog/generator-openapi', { options }]`

Example:

services: [{
  id: 'Orders Service',
  version: '1.0.0',
  specifications: [
    {
      type: 'openapi',
      artifactId: 'OrdersAPI-OPENAPI',
      version: 'latest',
      generator: ['@eventcatalog/generator-openapi', {
        // generator options here
      }]
    },
    {
      type: 'asyncapi',
      artifactId: 'OrdersEvents-ASYNCAPI',
      version: '2.0.0',
      generator: ['@eventcatalog/generator-asyncapi', {
        // generator options here
      }]
    }
  ]
}]

When a generator is configured, the plugin will:

Fetch the specification from Apicurio Registry
Save it to the service directory
Run the specified generator to process the specification
Pass the domain configuration to the generator if a domain is configured

Filtering schemas to services

When you assign schemas to a service, you can use a range of filtering options including exact matches, prefixes, suffixes, and includes.

Here are some examples of how to filter schemas to services.

exact matching example - Match schemas that exactly match the specified name

What is exact matching?

Exact matching is when the schema artifact ID exactly matches the specified name.

In this example, the Orders Service will send events with the artifact IDs order-placed, order-cancelled and receive commands with the artifact ID place-order.

Example artifacts in Apicurio Registry:

order-placed
order-cancelled
place-order
cancel-order

// ...
generators: [
  // Import schemas (using filters), assign them to services and domains
  [
    '@eventcatalog/generator-apicurio',
      {
        // The URL of your Apicurio Registry
        registryUrl: 'http://localhost:8080',
        // The services to assign schemas to (optional)
        services: [
          {
            id: 'Orders Service',
            version: '1.0.0',
            // Order service publishes events that match the artifact IDs
            sends: [{ events: ['order-placed', 'order-cancelled']}],
            // The Order service receives commands that match the artifact IDs
            receives: [{ commands: ['place-order', 'cancel-order']}],
          }
        ],
      },
  ],
];

suffix matching example - Match schemas that end with a specific string

What is suffix matching?

Suffix matching is when the artifact ID ends with the specified suffix.

In this example, the Orders Service will send events with a suffix of -placed and receive commands with a suffix of -command.

Example artifacts in registry:

order-placed
order-cancelled
place-order-command
cancel-order-command

// ...
generators: [
  // Import schemas (using filters), assign them to services and domains
  [
    '@eventcatalog/generator-apicurio',
      {
        // The URL of your Apicurio Registry
        registryUrl: 'http://localhost:8080',
        // The services to assign schemas to (optional)
        services: [
          {
            id: 'Orders Service',
            version: '1.0.0',
            // Order service publishes events with a suffix of `-placed`
            sends: [{ events: { suffix: '-placed' }}],
            // The Order service receives commands with a suffix of `-command`
            receives: [{ commands: { suffix: '-command' }}],
          }
        ],
      },
  ],
];

prefix matching example - Match schemas that start with a specific string

What is prefix matching?

Prefix matching is when the artifact ID starts with the specified prefix.

In this example, the Orders Service will send events with a prefix of order- and receive commands with a prefix of analytics-.

Example artifacts in registry:

order-placed
order-cancelled
analytics-place-order
analytics-cancel-order

// ...
generators: [
  // Import schemas (using filters), assign them to services and domains
  [
    '@eventcatalog/generator-apicurio',
      {
        // The URL of your Apicurio Registry
        registryUrl: 'http://localhost:8080',
        // The services to assign schemas to (optional)
        services: [
          {
            id: 'Orders Service',
            version: '1.0.0',
            // Order service publishes events with a prefix of `order-`
            sends: [{ events: { prefix: 'order-' }}],
            // The Order service receives commands with a prefix of `analytics-`
            receives: [{ commands: { prefix: 'analytics-' }}],
          }
        ],
      },
  ],
];

includes matching example - Match schemas that include a specific string

What is includes matching?

Includes matching is when the artifact ID contains the specified string anywhere in its name.

In this example, the Orders Service will send events that include the string order and receive commands that include the string analytics.

Example artifacts in registry:

order-placed
order-cancelled
analytics-place-order
analytics-cancel-order

// ...
generators: [
  // Import schemas (using filters), assign them to services and domains
  [
    '@eventcatalog/generator-apicurio',
      {
        // The URL of your Apicurio Registry
        registryUrl: 'http://localhost:8080',
        // The services to assign schemas to (optional)
        services: [
          {
            id: 'Orders Service',
            version: '1.0.0',
            // Order service publishes events that include `order`
            sends: [{ events: { includes: 'order' }}],
            // The Order service receives commands that include `analytics`
            receives: [{ commands: { includes: 'analytics' }}],
          }
        ],
      },
  ],
];

Message types - Document schemas as events, commands, or queries

What are message types?

You can document your schemas as different message types in EventCatalog:

events: Things that have happened (past tense)
commands: Requests to do something (imperative)
queries: Requests for information

In this example, the Orders Service sends events and receives both commands and queries.

// ...
generators: [
  [
    '@eventcatalog/generator-apicurio',
      {
        registryUrl: 'http://localhost:8080',
        services: [
          {
            id: 'Orders Service',
            version: '1.0.0',
            // Sends events
            sends: [{ events: { prefix: 'order-' }}],
            // Receives commands and queries
            receives: [
              { commands: ['place-order', 'cancel-order']},
              { queries: ['get-order-status']}
            ],
          }
        ],
      },
  ],
];

Example Configurations

The Apicurio Registry plugin is flexible to work with your use case. Here are a few examples of how you can configure the plugin.

Example configuration - Import all schemas (and versions) into EventCatalog

In this example we import all schemas from the Apicurio Registry into EventCatalog. No services or domains are configured or created. This is a simple way to import schemas into the catalog and keep them in sync with your documentation.

eventcatalog.config.js
  // ...rest of eventcatalog.config.js file
  generators: [
    [
      '@eventcatalog/generator-apicurio',
      {
        // The URL of your Apicurio Registry
        registryUrl: 'http://localhost:8080',

        // Include all versions of the schemas
        includeAllVersions: true,
      }
    ]
  ],
};

Example configuration - Assign schemas to services

In this example we assign schemas to services (producers and consumers in EventCatalog).

eventcatalog.config.js
  // ...rest of eventcatalog.config.js file
  generators: [
    [
      '@eventcatalog/generator-apicurio',
      {
        // The URL of your Apicurio Registry
        registryUrl: 'http://localhost:8080',
        // The services to assign schemas to (optional)
        services: [
          {
            id: 'Orders Service',
            version: '1.0.0',
            // Order service publishes events that match the artifact IDs
            sends: [{ events: ['order-placed', 'order-cancelled']}],
            // The Order service receives commands that match the artifact IDs
            receives: [{ commands: ['place-order', 'cancel-order']}],
          }
        ]
      }
    ]
  ],
};

Example configuration - Assign schemas to services (with filters)

In this example we assign schemas to services (producers and consumers in EventCatalog) but we use filters to match the schemas.

eventcatalog.config.js
  // ...rest of eventcatalog.config.js file
  generators: [
    [
      '@eventcatalog/generator-apicurio',
      {
        // The URL of your Apicurio Registry
        registryUrl: 'http://localhost:8080',
        // The services to assign schemas to (optional)
        services: [
          {
            id: 'Orders Service',
            version: '1.0.0',
            // Order service publishes events that start with `order-`
            sends: [{ events: { prefix: 'order-' }}],
            // The Order service receives commands that end with `-command`
            receives: [{ commands: { suffix: '-command' }}],
          }
        ]
      }
    ]
  ],
};

Example configuration - Assign schemas to services within a domain

In this example we assign schemas to services (producers and consumers in EventCatalog) and we also assign them to a domain.

eventcatalog.config.js
  // ...rest of eventcatalog.config.js file
  generators: [
    [
      '@eventcatalog/generator-apicurio',
      {
        // The URL of your Apicurio Registry
        registryUrl: 'http://localhost:8080',
        // The services to assign schemas to (optional)
        services: [
          {
            id: 'Orders Service',
            version: '1.0.0',
            // Order service publishes events
            sends: [{ events: ['order-placed', 'order-cancelled']}],
            // The Order service receives commands
            receives: [{ commands: ['place-order', 'cancel-order']}],
          }
        ],
        // The domain to assign the service to
        // if it does not exist, it will be created
        domain: {
          id: 'orders',
          name: 'Orders',
          version: '1.0.0',
        }
      }
    ]
  ],
};

Example configuration - Attach specifications and use nested generators

In this example we attach OpenAPI and AsyncAPI specifications to a service and use the respective EventCatalog generators to process them.

eventcatalog.config.js
  // ...rest of eventcatalog.config.js file
  generators: [
    [
      '@eventcatalog/generator-apicurio',
      {
        // The URL of your Apicurio Registry
        registryUrl: 'http://localhost:8080',
        // The services to assign schemas to
        services: [
          {
            id: 'Orders Service',
            version: '1.0.0',
            // Attach specifications from Apicurio Registry
            specifications: [
              {
                type: 'openapi',
                artifactId: 'OrdersAPI-OPENAPI',
                version: 'latest',
                // Use the OpenAPI generator to process the specification
                generator: ['@eventcatalog/generator-openapi', {
                  // Pass options to the OpenAPI generator if needed
                }]
              },
              {
                type: 'asyncapi',
                artifactId: 'OrdersEvents-ASYNCAPI',
                version: '2.0.0',
                // Use the AsyncAPI generator to process the specification
                generator: ['@eventcatalog/generator-asyncapi', {
                  // Pass options to the AsyncAPI generator if needed
                }]
              }
            ],
            // You can also assign schemas directly
            sends: [{ events: { prefix: 'order-' }}],
            receives: [{ commands: ['place-order', 'cancel-order']}],
          }
        ],
        domain: {
          id: 'orders',
          name: 'Orders',
          version: '1.0.0',
        }
      }
    ]
  ],
};

tip

When using nested generators, make sure to:

Install the respective plugins:

npm install @eventcatalog/generator-openapi @eventcatalog/generator-asyncapi

Obtain license keys from EventCatalog Cloud (14-day free trial available)
Add the license keys to your .env file:

EVENTCATALOG_LICENSE_KEY_OPENAPI=your-openapi-license-key
EVENTCATALOG_LICENSE_KEY_ASYNCAPI=your-asyncapi-license-key

See OpenAPI Plugin Docs | AsyncAPI Plugin Docs for more information.

Example configuration - Service relationships with writesTo and readsFrom

In this example we document service-to-service relationships using writesTo and readsFrom to show how services interact with each other.

eventcatalog.config.js
  // ...rest of eventcatalog.config.js file
  generators: [
    [
      '@eventcatalog/generator-apicurio',
      {
        // The URL of your Apicurio Registry
        registryUrl: 'http://localhost:8080',
        // The services to assign schemas to
        services: [
          {
            id: 'Orders Service',
            version: '1.0.0',
            sends: [{ events: { prefix: 'order-' }}],
            receives: [{ commands: ['place-order', 'cancel-order']}],
            // This service writes to Inventory Service and Notifications Service
            writesTo: [
              { id: 'Inventory Service', version: '1.0.0' },
              { id: 'Notifications Service', version: '1.0.0' }
            ]
          },
          {
            id: 'Inventory Service',
            version: '1.0.0',
            sends: [{ events: { prefix: 'inventory-' }}],
            // This service reads from Orders Service
            readsFrom: [
              { id: 'Orders Service', version: '1.0.0' }
            ]
          },
          {
            id: 'Notifications Service',
            version: '1.0.0',
            receives: [{ events: ['order-placed', 'order-cancelled']}],
            // This service reads from Orders Service
            readsFrom: [
              { id: 'Orders Service', version: '1.0.0' }
            ]
          }
        ],
        domain: {
          id: 'orders',
          name: 'Orders',
          version: '1.0.0',
        }
      }
    ]
  ],
};

This configuration will create service relationships in EventCatalog, making it easier to visualize and understand how services communicate with each other.

Example configuration - Multiple domains with version management

In this example we configure the plugin multiple times to document different domains, and we use includeAllVersions to track schema evolution.

"Why configure the plugin multiple times?"

The generator can be configured as many times as you want. In this example we configure the plugin twice, once for each domain.

eventcatalog.config.js
  // ...rest of eventcatalog.config.js file
  generators: [
    // Retail domain
    [
      '@eventcatalog/generator-apicurio',
      {
        registryUrl: 'http://localhost:8080',
        includeAllVersions: true,
        services: [
          {
            id: 'Orders Service',
            version: '1.0.0',
            sends: [{ events: { prefix: 'order-' }}],
            receives: [{ commands: ['place-order', 'cancel-order']}],
          },
          {
            id: 'Inventory Service',
            version: '1.0.0',
            sends: [{ events: { prefix: 'inventory-' }}],
            receives: [{ events: { prefix: 'order-' }}],
          },
        ],
        domain: {
          id: 'retail',
          name: 'Retail',
          version: '1.0.0',
        }
      },
    ],
    // Communications domain
    [
      '@eventcatalog/generator-apicurio',
      {
        registryUrl: 'http://localhost:8080',
        includeAllVersions: true,
        services: [
          {
            id: 'Notifications Service',
            version: '1.0.0',
            receives: [
              { events: ['user-registered']},
              { events: ['order-placed']},
              { events: ['shipment-created']},
            ],
          },
        ],
        domain: {
          id: 'communications',
          name: 'Communications',
          version: '1.0.0',
        }
      },
    ],
  ],
};

Need help?

If you have questions or need help, you can join our Discord community or refer to the Apicurio Registry examples on GitHub.

Overview​

Required Configuration Options​

Optional Configuration Options​

Services​

Domains​

Specifications​

Filtering schemas to services​

Example Configurations​

Need help?​

Overview

Required Configuration Options

Optional Configuration Options

Services

Domains

Specifications

Filtering schemas to services

Example Configurations

Need help?