Features
Dual-license
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
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.
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.