Skip to main content

Features

License: 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.

x-eventcatalog-message-type example
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​

Added in @eventcatalog/generator-openapi@3.0.0

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.

x-eventcatalog-message-type example
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​

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.