Features
Dual-license| Feature | Use cases |
|---|---|
| Mapping messages as commands, queries or events | OpenAPI does not have the concept of commands, queries or events, everything is a message (endpoint). Using the EventCatalog extension you can map your payloads as commands, queries or events. |
| Assign owners to your domains, services and messages | Set ownership of your service, and it's messages. Let your teams understand who owns what. |
| Creating draft domains, services and messages | Evolve your specifications. Mark endpoints as draft for your teams. This can help you highlight which endpoints are still in development or draft. |
| Map many OpenAPI files to a single service | If your service exposes multiple APIs, you can map many OpenAPI files to a single service. |
| Custom versioning with x-eventcatalog-message-version | By default this plugin will use the OpenAPI version for all your messages. You can use the x-eventcatalog-message-version extension to specify a different version for a particular message. |
| Fetch OpenAPI files by URL | 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. |
| Authenticate remote URLs | Use HTTP headers to access protected OpenAPI files from authenticated URLs. |
| Define EventCatalog ids and names in your OpenAPI specification file | EventCatalog messages (commands, queries and events) have two important properties, these are id and name. |
| Define messages a service sends or receives | By default all messages in your OpenAPI spec file are documented as messages that are received by your service (e.g a route with /getOrders will be a query/command/event that the service accepts). You can override this by using the x-eventcatalog-message-action extension. |
| Deprecating messages | To mark messages as deprecated you can use the deprecated field or the x-eventcatalog-deprecated-date and x-eventcatalog-deprecated-message extensions. |
| Persist markdown | When you generate your OpenAPI 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 OpenAPI files. |
| Automatic versioning | When you change versions in your OpenAPI file and run generate, your services and messages are automatically versioned. This allows you to keep an audit log of changes between OpenAPI files, schemas and more. |
| Downloading schemas | If your messages have schemas 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. |
| Parse examples from operations | Automatically extract request body and response examples from your OpenAPI operations and save them as JSON files alongside your messages in EventCatalog. |
| Define consumer services | Declare which services consume the messages generated from an OpenAPI spec, with optional route-based filtering to limit which messages each consumer sends to. |
| Group messages | Group related messages together in the visualiser for easier navigation of large APIs. |
Define consumer services
EventCatalog will document who owns the service. You can also define consumers of your APIs. This can help you document which services are calling your endpoints to help with future maintenance of your APIs and develop a shared understanding.
Add a consumers array to any service in your generator config to declare which other services send requests to that service. Each consumer entry needs at minimum an id; a version and routes filter are both optional.
generators: [
[
'@eventcatalog/generator-openapi',
{
services: [
{
path: path.join(__dirname, 'openapi-files', 'orders-service.yml'),
id: 'orders-service',
consumers: [
// Sends to all messages from the service
{ id: 'audit-service' },
// Pinned to a specific version
{ id: 'billing-service', version: '1.0.0' },
// Only messages whose path ends with /events
{ id: 'notifications-service', routes: [{ suffix: '/events' }] },
// Only messages matching a wildcard pattern
{ id: 'analytics', routes: [{ match: '/api/*/track' }] },
],
},
],
domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
},
],
],
Route filtering
Route filters let you limit which messages a consumer sends to based on the API path of each operation. Omitting routes means the consumer sends to every message from the service.
Each filter object supports four matching strategies:
| Key | Behaviour | Example |
|---|---|---|
path | Exact match | { path: '/orders/{id}' } |
prefix | Path starts with the value | { prefix: '/orders' } |
suffix | Path ends with the value | { suffix: '/events' } |
match | Wildcard match (* spans one or more path segments) | { match: '/api/*/track' } |
All keys in a single filter object must match (AND). Multiple filter objects in the array are evaluated as OR, so a message is included if it satisfies any one of them.
// Exact path only
routes: [{ path: '/orders/{id}' }]
// Paths under /orders OR paths ending with /events
routes: [{ prefix: '/orders' }, { suffix: '/events' }]
// Path must start with /api AND end with /events (AND within one object)
routes: [{ prefix: '/api', suffix: '/events' }]
// Wildcard: matches /api/orders/track, /api/payments/track, etc.
routes: [{ match: '/api/*/track' }]
How consumers are looked up and updated
When the generator runs, each consumer service is looked up by id and version. The consumer service must already exist in the catalog. If it cannot be found, the consumer entry is skipped; the generator does not create a service page or add the consumer to the configured domain.
If the consumer already exists in the catalog, it is updated in-place so its existing markdown, location, and metadata are preserved. The sends list on the consumer is merged with the incoming messages, with deduplication applied. If a consumer entry already tracks a versioned message, its version is updated to the latest value from the spec.
If another generator creates the consumer service, place that generator before the OpenAPI generator that references it. Otherwise, the consumer relationship is skipped for that generation run.
Mapping messages as commands, queries or events
OpenAPI does not distinguish between commands, events and queries, everything is a message.
Using the EventCatalog custom OpenAPI extension you can specify if your messages are queries, commands or events.
You can use the x-eventcatalog-message-type to specify the type of message.
By default everything parsed by EventCatalog is a query, unless you specify with the x-eventcatalog-message-type extension.
paths:
/pets:
get:
summary: List all pets
operationId: listPets
tags:
- pets
x-eventcatalog-message-type: query # command, query, or event
parameters:
- name: limit
in: query
description: How many items to return at one time (max 100)
required: false
schema:
type: integer
maximum: 100
format: int32
Assign owners to your domains, services and messages
You can set owners to your domains and services. Setting owners to services will also set the owner to all messages in the service.
To do this you can use the owners property in the service or domain.
// ..rest of file
generators: [
[
'@eventcatalog/generator-openapi',
{
services: [
// here we assign owners to the service (owners documented in EventCatalog)
// The owners will also be set to all messages in the service
{ path: path.join(__dirname, 'openapi-files', 'orders-service.yml'), id: 'orders-service', owners: ['dboyne', 'team-1'] },
// If you don't want to set owners to all messages you can use the setMessageOwnersToServiceOwners flag
{ path: path.join(__dirname, 'openapi-files', 'orders-service.yml'), id: 'orders-service', owners: ['dboyne', 'team-1'], setMessageOwnersToServiceOwners: false },
],
// You can also set owners to the domain, this does not cascade to the services or messages
domain: { id: 'orders', name: 'Orders', version: '0.0.1', owners: ['dboyne', 'team-1'] },
},
],
],
};
Creating draft domains, services and messages
You can create draft domains, services and messages in EventCatalog from your OpenAPI files.
Use case:
- You want to create a service in EventCatalog that is not yet implemented or going through feedback/design phase.
- You want to introduce a new endpoint to your service, but warn users that it is not yet implemented or still in development or draft.
- You want to introduce a whole new domain, but warn users everything in the domain is still in development or draft.
Getting started
You have a few options to create draft resources from your specification files.
domain.draft- If true, the domain will be drafted in EventCatalog with all it's services / messages.service.draft- If true, the service will be drafted in EventCatalog with all it's endpoints / messages.
You can also choose to use OpenAPI extensions to create draft resources.
x-eventcatalog-draft- If true, the resource will be drafted in EventCatalog (e.g service and messages).
Example of creating draft resources through domains (configuration)
Setting the draft property to true will create a draft domain with all it's services and messages in EventCatalog.
// ..rest of file
generators: [
[
'@eventcatalog/generator-openapi',
{
domain: { id: 'orders', name: 'Orders', version: '0.0.1', draft: true },
},
],
],
};
Example of creating draft resources through services (configuration)
Setting the draft property to true will create a draft service with all it's messages in EventCatalog.
// ..rest of file
generators: [
[
'@eventcatalog/generator-openapi',
{
services: [
{ path: path.join(__dirname, 'openapi-files', 'orders-service.yml'), id: 'orders-service', draft: true },
],
},
],
],
};
In this example the Orders Service and all it's messages will be marked as draft in EventCatalog.
Example marking service as draft (OpenAPI extension)
Setting the x-eventcatalog-draft extension to true will mark the service as draft in EventCatalog.
openapi: 3.0.0
info:
title: Pet Service
version: 1.0.0
# Here we mark the service as draft
x-eventcatalog-draft: true
paths:
/pets:
get:
summary: List all pets
operationId: listPets
tags:
- pets
In this example the Pet Service and the /pets endpoint will be marked as draft in EventCatalog.
Example marking a message as draft (OpenAPI extension)
Setting the x-eventcatalog-draft extension to true will mark the message as draft in EventCatalog.
openapi: 3.0.0
info:
title: Pet Service
version: 1.0.0
paths:
/pets:
get:
summary: List all pets
operationId: listPets
x-eventcatalog-draft: true # This will mark the message as draft
tags:
- pets
In this example we mark the message listPets as draft but the service is not marked as draft in EventCatalog.
This can be useful if you want to introduce a new endpoint, but warn users that it is not yet implemented or still in development or draft.
Map many OpenAPI files to a single service
If your service exposes multiple APIs, you can map many OpenAPI files to a single service.
One service configuration entry represents one EventCatalog service version. Every file in the path array is attached to that service version.
// ..rest of file
generators: [
[
'@eventcatalog/generator-openapi',
{
services: [
// Here we map two OpenAPI files to a single service
{
path: [
path.join(__dirname, 'openapi-files', 'orders-public-api.yml'),
path.join(__dirname, 'openapi-files', 'orders-admin-api.yml')
],
id: 'orders-service', version: '3.0.0', owners: ['dboyne', 'team-1']
},
],
// You can also set owners to the domain, this does not cascade to the services or messages
domain: { id: 'orders', name: 'Orders', version: '0.0.1', owners: ['dboyne', 'team-1'] },
},
],
],
};
How does mapping multiple OpenAPI files to a single service work?
The OpenAPI plugin parses every file in the path array and adds every specification to the same service version.
When version is configured on the service entry, it is used for the service and its generated messages. When it is omitted, the highest OpenAPI info.version in the array is selected using semantic version ordering.
The files in a path array do not create separate historical service records. To model service history, configure a separate service entry with an explicit version for each OpenAPI file. See OpenAPI workflows for examples.
You can try this demo out for yourself by running the mapping-many-openapi-files-to-a-service example.
Custom versioning with x-eventcatalog-message-version
By default this plugin will use the OpenAPI version for all your messages.
You can use the x-eventcatalog-message-version extension to specify a different version for a particular message.
openapi: '3.0.0'
info:
title: Test Service
version: 1.0.0
paths:
/pets:
get:
summary: List all pets
operationId: listPets
tags:
- pets
x-eventcatalog-message-version: 5.0.0
In the example above, the message listPets will be versioned as 5.0.0 and all other messages will be versioned as 1.0.0.
This feature lets you control the version of your messages individually.
Fetch OpenAPI files by URL
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 OpenAPI file by public URL
{ path: "https://raw.githubusercontent.com/event-catalog/generator-openapi/refs/heads/main/examples/product-api/openapi.yml", id: "Product Service"},
// Add OpenAPI file using file system
{ path: path.join(__dirname, 'openapi-files', 'fraud-detection-service.yml'), "Fraud Service"}
],
domain: { id: 'payment', name: 'Payment', version: '0.0.1' },
// Parse the YML before we save it to the catalog (optional) (http://localhost:3000/docs/development/plugins/open-api/api#saveParsedSpecFile)
saveParsedSpecFile: true,
// Run in debug mode, for extra output, if your AsyncAPI fails to parse, it will tell you why
debug: true,
},
],
The path can be the file path to your local file system or an external URL. The external URL has to be accessible from the machine running the generator.
Authenticate remote URLs
When fetching OpenAPI files from authenticated URLs, provide HTTP headers using the headers property.
This is useful for accessing private specifications from internal registries, API gateways, or other protected endpoints.
[
'@eventcatalog/generator-openapi',
{
services: [
{
path: "https://api.example.com/specs/orders-service.openapi.yml",
id: "orders-service",
headers: {
Authorization: 'Bearer your-api-token',
'X-Api-Key': 'your-api-key'
}
}
],
domain: { id: 'orders', name: 'Orders', version: '0.0.1' }
}
]
The headers are passed with every HTTP request when fetching the OpenAPI file from the specified URL.
Define EventCatalog ids and names in your OpenAPI specification file
EventCatalog messages (commands, queries and events) have two important properties, these are id and name.
- id - The id of your message (used for url slugs)
- name - Friendly name for your message in EventCatalog (used in the UI)
The OpenAPI generator will set a default value for the name and id using the operationId or the service name.
If you want more control, you can use the x-eventcatalog-message-name and x-eventcatalog-message-id extensions to specify the id and name value.
paths:
/pets:
get:
summary: List all pets
operationId: listPets
tags:
- pets
x-eventcatalog-message-type: query # command, query, or event
x-eventcatalog-message-id: list-pets # Used as EventCatalog ID (slug) and reference to the resource
x-eventcatalog-message-name: List pets # Used by EventCatalog as friendly name for the message
parameters:
- name: limit
in: query
description: How many items to return at one time (max 100)
required: false
schema:
type: integer
maximum: 100
format: int32
Define messages a service sends or receives
By default all messages in your OpenAPI spec file are documented as messages that are received by your service (e.g a route with /getOrders will be a query/command/event that the service accepts).
If you want to specify the relationship of your messages and services (sends or receives) you can do this using the custom extension x-eventcatalog-message-action. Which you can define in your OpenAPI files.
paths:
/pets/{petId}/vaccinated:
post:
summary: Notify that a pet has been vaccinated
operationId: petVaccinated
tags:
- pets
# This tells eventcatalog that this message is sent from this service.
x-eventcatalog-message-action: sends
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Vaccination'
required: true
responses:
'200':
description: Notification that the pet has been vaccinated successfully
default:
description: unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
In the example above, when the generator runs, it will put the message petVaccinated as a message the petstore service sends.
Adding prefix to all messages
If you want more control over the ids of the generated messages you can
- Define ids nad names using the
x-eventcatalog-message-idandx-eventcatalog-message-nameextensions. - Add a prefix to the id of the generated messages (see below)
- prefix (with a string)
- prefix (with custom separator)
- prefix (with service id)
This will add a prefix to the id of the generated messages. For example a message with the operationId getOrders with a configured prefix of hello- will be hello-getOrders.
generators: [
[
'@eventcatalog/generator-openapi',
{
messages: { id: { prefix: 'hello' } },
},
],
],
This will add a prefix to the id of the generated messages. For example a message with the operationId getOrders with a configured prefix of hello- and separator of _ will be hello_getOrders.
generators: [
[
'@eventcatalog/generator-openapi',
{
messages: { id: { prefix: 'hello', separator: '_' } },
},
],
],
This will add the service id to the id of the generated messages. For example a message with the operationId getOrders and the service id orders-service will be orders-service-getOrders.
generators: [
[
'@eventcatalog/generator-openapi',
{
messages: { id: { prefixWithServiceId: true } },
},
],
],
Deprecating messages
To mark messages as deprecated you can use the deprecated field or the x-eventcatalog-deprecated-date and x-eventcatalog-deprecated-message extensions.
Deprecated as a boolean
OpenAPI natively supports deprecating messages using the deprecated field.
paths:
/pets:
get:
summary: List all pets
operationId: listPets
deprecated: true
When this deprecated field is set to true, the message will be rendered in EventCatalog with a banner indicating that the message is deprecated.
Deprecated as an object
If you want more fine grained control over the deprecation date and message, you can use the x-eventcatalog-deprecated-date and x-eventcatalog-deprecated-message extensions.
paths:
/pets:
get:
summary: List all pets
operationId: listPets
x-eventcatalog-deprecated-date: 2026-05-01
x-eventcatalog-deprecated-message: |
This message is **being deprecated** and replaced by the new service **InventoryService**.
Please contact the [team for more information](mailto:inventory-team@example.com) or visit our [website](https://eventcatalog.dev).
This will render a banner in EventCatalog indicating that the message will be deprecated on 2026-05-01.
Persist markdown
When you generate your OpenAPI 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 OpenAPI files.
Automatic versioning
When you change versions in your OpenAPI file and run generate, your services and messages are automatically versioned. This allows you to keep an audit log of changes between OpenAPI 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 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 OpenAPI file.
Group messages
When a service sends or receives many messages, the visualiser can become crowded. The groupMessagesBy option lets you automatically group related messages together so they collapse into a single node in the visualiser map, making your architecture easier to understand at a glance.
To learn more about how groups work in the visualiser, see Grouping messages.
Three strategies are supported:
| Strategy | How the group is determined |
|---|---|
x-extension | Reads the x-eventcatalog-group field on each OpenAPI operation |
path-prefix | Derives the group from the first meaningful URL path segment, skipping common prefixes like api, v1, v2 |
single-group | Places every operation into a single group called operations |
Use the x-extension strategy
Set groupMessagesBy: 'x-extension' and add x-eventcatalog-group to each operation you want to group.
generators: [
[
'@eventcatalog/generator-openapi',
{
services: [{ path: './openapi.yml', id: 'my-service' }],
groupMessagesBy: 'x-extension',
},
],
],
paths:
/pets/{petId}/adopt:
post:
x-eventcatalog-group: Adoptions
summary: Adopt a pet
operationId: adoptPet
Use the path-prefix strategy
Set groupMessagesBy: 'path-prefix' and the generator derives the group name automatically from the URL. No changes to your OpenAPI file are needed.
generators: [
[
'@eventcatalog/generator-openapi',
{
services: [{ path: './openapi.yml', id: 'my-service' }],
groupMessagesBy: 'path-prefix',
},
],
],
The generator reads the first meaningful path segment and capitalizes it as the group name. Common technical prefixes are skipped automatically.
| Path | Group |
|---|---|
/pets/{petId} | Pets |
/api/v1/billing/invoices | Billing |
/health | (no group, single segment) |
/pets | (no group, single segment) |
Use the single-group strategy
Set groupMessagesBy: 'single-group' to place every operation into one group called operations, regardless of its path or any extensions. No changes to your OpenAPI file are needed.
generators: [
[
'@eventcatalog/generator-openapi',
{
services: [{ path: './openapi.yml', id: 'my-service' }],
groupMessagesBy: 'single-group',
},
],
],
This is useful for very large APIs where path-prefix still leaves too many ungrouped nodes. Every message collapses into a single operations node in the visualiser.
Once grouped, messages appear as a compact stacked card in the visualiser. Click the group to expand it and see the full downstream graph — channels, consumers, and producers — just as if the messages were ungrouped. See Grouping messages for more details.
Parse examples from operations
When parseExamples is enabled (the default), the generator reads examples defined on your OpenAPI operations and writes them as JSON files into each message's examples folder in EventCatalog.
Both request body examples and response examples are supported, across the single example and named examples formats from the OpenAPI specification.
How examples are named
| Source | File name |
|---|---|
Single request body example | example.json |
Named request body examples (e.g. dog) | dog.json |
Single response example (e.g. status 200) | response-200.json |
Named response examples (e.g. status 200, name dog) | response-200-dog.json |
OpenAPI example formats
paths:
/pets:
post:
operationId: createPet
requestBody:
content:
application/json:
example:
name: Fido
tag: dog
paths:
/pets:
post:
operationId: createPet
requestBody:
content:
application/json:
examples:
dog:
value:
name: Fido
tag: dog
cat:
value:
name: Whiskers
tag: cat
paths:
/pets:
post:
operationId: createPet
responses:
'200':
content:
application/json:
examples:
dog:
value:
id: 1
name: Fido
cat:
value:
id: 2
name: Whiskers
To disable example parsing, set parseExamples: false in your generator configuration.
generators: [
[
'@eventcatalog/generator-openapi',
{
services: [
{ path: path.join(__dirname, 'openapi-files', 'orders-service.yml'), id: 'orders-service' }
],
parseExamples: false,
},
],
],