Skip to main content

Features

License: Dual-license

Mapping messages as commands and 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 events or commands (query support coming soon).

You can use the x-eventcatalog-message-type to specify the type of message.

By default everything parsed by EventCatalog is a command, unless you specify with the x-eventcatalog-message-type extension.

x-eventcatalog-message-type example
paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      tags:
        - pets
      x-eventcatalog-message-type: query # command or event (query support soon)
      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​

Added in @eventcatalog/generator-openapi@2.3.0

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.

x-eventcatalog-message-action example
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.

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.