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. |
| 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. |
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.
// ..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-service-v1.yml'),
path.join(__dirname, 'openapi-files', 'orders-service-v2.yml')
],
id: 'orders-service', 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 will parse all the files in the path array. The are ordered by version (info.version).
Old versions are parsed first and versioned in your catalog along side the messages.
The latest version is parsed last and will be used as the current version in your catalog.
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.
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.
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.