Features
AsyncAPI Extensions​
AsyncAPI have extensions which are the attributes allowing to cover specific requirements not covered by the spec.
EventCatalog relies on the extensions to cover some specific concepts in Event Driven Architecture.
Mapping messages events, commands or queries​
AsyncAPI does not distinguish between commands, events and queries, everything is a message.
Using the EventCatalog custom AsyncAPI extension x-eventcatalog-message-type you can specify if your messages are events, command or queries.
You can use the x-eventcatalog-message-type to specify the type of message.
By default everything parsed by EventCatalog is an event, unless you specify with the x-eventcatalog-message-type extension.
components:
messages:
OrderCreated:
description: 'Event triggered when an order is created'
x-eventcatalog-message-type: event // event/query/command
You can see more examples of the extension on the demo project.
Defining message ownership roles​
AsyncAPI specification files do not define who owns the message and it's contract. Your AsyncAPI file my define messages your service consumes and produces but that service may not be the service that owns it's contract. (e.g An order service that consumes a Payment event. The order service (AsyncAPI file) would specify it consumes the payment event, but it is not the owner of the contract or event).
By default when you integrate your AsyncAPI files into EventCatalog, EventCatalog will assume your service (AsyncAPI file) owns the messages and will document them this way.
If you want to define ownership of messages in your files you can use the x-eventcatalog-role extension in your AsyncAPI files. This let's you specify if your service is a provider (owner) or the message or just a consumer (client) of the message.
The available extension values are:
provider: Generator will generate a new message considering the service is the owner of message contract (default).client: Generator will consider the message as a sent/received message in service but will NOT generate or modify the message in EventCatalog.
components:
messages:
SendOrderConfirmation:
description: 'Command received to ask for sending an Order confirmation notification'
x-eventcatalog-role: client // Define the ownership. This example shows the service is a client of the message and does not own the message.
You can see more examples of the extension on the demo project.
AsyncAPI specification files do not define who owns the message and it's contract. Your AsyncAPI file my define messages your service consumes and produces but that service may not be the service that owns it's contract. (e.g An order service that consumes a Payment event. The order service (AsyncAPI file) would specify it consumes the payment event, but it is not the owner of the contract or event).
By default when you integrate your AsyncAPI files into EventCatalog, EventCatalog will assume your service (AsyncAPI file) owns the messages and will document them this way.
If you want to define ownership of messages in your files you can use the x-eventcatalog-role extension in your AsyncAPI files. This let's you specify if your service is a provider (owner) or the message or just a consumer (client) of the message.
The available extension values are:
provider: Generator will generate a new message considering the service is the owner of message contract (default).client: Generator will consider the message as a sent/received message in service but will NOT generate or modify the message in EventCatalog.
components:
messages:
SendOrderConfirmation:
description: 'Command received to ask for sending an Order confirmation notification'
x-eventcatalog-role: client // Define the ownership. This example shows the service is a client of the message and does not own the message.
You can see more examples of the extension on the demo project.
Defining message versions​
In EventCatalog you can version your domains, services and all your messages. This can be useful as you can specify which version of a message your service produces or consumes.
Using the AsyncAPI generator by default the messages that are generated all use the AsyncAPI version.
In the example below the service Account Service will be documented using the version 1.0.0. The UserSignedUp event will be documented as version 1.0.0 (taken from the AsyncAPI version).
asyncapi: 3.0.0
info:
title: Account Service
# This version is uses for your service and all messages
version: 1.0.0
description: This service is in charge of processing user signups
contact:
name: Awesome Team
url: https://example.com
email: support@asyncapi.org
# rest of AsyncAPI file...
UserSignedUp:
description: 'Sign up a user'
x-eventcatalog-message-version: 2.0.0
tags:
- name: 'New'
description: 'New event'
payload:
type: object
properties:
displayName:
type: string
description: Name of the user
email:
type: string
format: email
description: Email of the user
Defining message versions​
If you want to version your messages separate from the AsyncAPI file you can use the x-eventcatalog-message-version extension.
Using the x-eventcatalog-message-version extension you can specify individual message versions.
In the example below the service Account Service will be documented using the version 1.0.0. The UserSignedUp event will be documented as version 2.0.0.
asyncapi: 3.0.0
info:
title: Account Service
# This version is uses for your service and all messages
version: 1.0.0
description: This service is in charge of processing user signups
contact:
name: Awesome Team
url: https://example.com
email: support@asyncapi.org
# rest of AsyncAPI file...
UserSignedUp:
description: 'Sign up a user'
# Here we set the version of this message to 2.0.0.
x-eventcatalog-message-version: 2.0.0
tags:
- name: 'New'
description: 'New event'
payload:
type: object
properties:
displayName:
type: string
description: Name of the user
email:
type: string
format: email
description: Email of the user
# rest of AsyncAPI file...
x-eventcatalog-message-version is optional per message, by default the AsyncAPI version will be used per message unless you specify the x-eventcatalog-message-version version.
Parsing $ref values and message schemas​
Your AsyncAPI file may have references to other files/schemas in it. When using this with EventCatalog it's recommended to use the saveParsedSpecFile field.
Setting this value to true, will parse your specification file and remove any $ref values, as EventCatalog cannot parse $ref values when hosted in the project.
When your AsyncAPI file is parsed, by default the schemas will also be parsed. If you want to keep them as they are you can also use the parseSchemas flag. Setting this to false will keep your schemas as they are.
Persist markdown​
When you generate your AsyncAPI 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 AsyncAPI files.
Fetch AsyncAPI 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 AsyncAPI file by public URL
{ path: "https://raw.githubusercontent.com/event-catalog/eventcatalog-asyncapi-example/refs/heads/main/asyncapi-files/payment-service.yml", id: "Payment Service"},
// Add AsyncAPI file using file system
{ path: path.join(__dirname, 'asyncapi-files', 'fraud-detection-service.yml'), "Fraud Service"}
],
domain: { id: 'payment', name: 'Payment', version: '0.0.1' },
// Run in debug mode, for extra output, if your AsyncAPI fails to parse, it will tell you why
debug: true
},
],
Automatic versioning​
When you change versions in your AsyncAPI file and run generate, your services and messages are automatically versioned. This allows you to keep an audit log of changes between AsyncAPI 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 (e.g avro, json) 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 AsyncAPI file.
Example​
See the eventcatalog-asyncapi-example for a working example.