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.
Mapping channels into EventCatalog​
EventCatalog supports Channels (see demo). This let's you document how messages or organized and transported in your event-driven architecture.
AsyncAPI also supports documenting channels. These can be added using the channels
object. (see example).
Channels can give your developers more insights into how messages are transported between services (e.g producers and consumers). Channels support dynamic naming, protocol definition and can be assigned to messages.
Documenting channels is off by default but you can turn this on using the parseChannels
flag in your generator.
Setting custom versions for channels​
EventCatalog supports versioning of channels. By default the version of the channel documented is the AsyncAPI version (you specify in the info object).
If you want more flexibility and document your channels individually you can use the x-eventcatalog-channel-version
extension.
Example of a channel with custom version
info:
title: Streetlights Kafka API
# Global version of this service (used by default)
version: 1.0.0
channels:
lightingMeasured:
address: 'smartylighting.streetlights.1.0.event.{streetlightId}.lighting.measured'
bindings:
kafka:
topic: 'my-topic'
partitions: 3
title: 'Lighting Measured Channel'
summary: 'Inform about environmental lighting conditions of a particular streetlight.'
messages:
lightMeasured:
$ref: '#/components/messages/lightMeasured'
description: The topic on which measured values may be produced and consumed.
parameters:
streetlightId:
$ref: '#/components/parameters/streetlightId'
# The version of the channel
x-eventcatalog-channel-version: 2.0.0
# AsyncAPI file contents...
When parseChannels
is set to true, running the generate command will document your channels and all messages that are assigned to that channel.
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,
// Parse and add channels to your eventcatalog from the AsyncAPI spec files
parseChannels: 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.