Plugin Configuration

Overview

The EventCatalog OpenAPI plugin is configured in the eventcatalog.config.js file inside the generators array.

Required Configuration Options

Option	Type	Required	Description
services	Service[]	Yes	List of OpenAPI files to add to your catalog
licenseKey	string	Yes*	License key for the plugin. Get a 14-day trial at EventCatalog Cloud. Can also be set via EVENTCATALOG_LICENSE_KEY_OPENAPI environment variable.

Service Configuration

Each service in the services array requires the following properties:

Property	Type	Required	Description
id	string	Yes	EventCatalog ID for the service.
path	string	Yes	Path to your OpenAPI file or remote URL to the OpenAPI file
owners	string[]	No	Owners of the service. You can assign EventCatalog users or teams to services.
setMessageOwnersToServiceOwners	boolean	No	If true, the owners of the service will be set to the owners of the messages in the OpenAPI file (default is true).

Optional Configuration Options

Option	Type	Default	Description
domain	object	-	Domain to associate all configured services with
domain.id	string	-	Domain identifier
domain.name	string	-	Domain display name
domain.version	string	-	Domain version
writeFilesToRoot	boolean	false	Write OpenAPI messages to root instead of service folder. By default all domains, services and messages will be grouped in the folder directory structure.
saveParsedSpecFile	boolean	false	Parse and save expanded OpenAPI spec (helpful for files with $refs)
sidebarBadgeType	string	HTTP_METHOD	(Added in v5.0.1) Decides what badges are shown in the documentation sidebar. HTTP_METHOD shows HTTP methods as badges, MESSAGE_TYPE shows QUERY, COMMAND or EVENT as badges.
httpMethodsToMessages	object	-	(Added in v5.0.2) Gives you the ability to map HTTP methods (GET, POST, PUT, DELETE, PATCH, etc.) to message types (command, query, event). By default OpenAPI will map your requests to queries, you can use this property to change this behavior or use the x-eventcatalog-message-type extension to set the message type for each request. If you use the x-eventcatalog-message-type extension in your spec file, this will be used.

Example Configuration

eventcatalog.config.js

import path from "path";
import url from "url";

const __dirname = path.dirname(url.fileURLToPath(import.meta.url));

/** @type {import('@eventcatalog/core/bin/eventcatalog.config').Config} */
export default {
  cId: "10b46030-5736-4600-8254-421c3ed56e47",
  title: "MetaRetail Inc",
  tagline: "Fake Retail Company for EventCatalog Demo",
  organizationName: "MetaRetail Inc",
  homepageLink: "https://eventcatalog.dev/",
  editUrl: "https://github.com/boyney123/eventcatalog-demo/edit/master",
  // By default set to false, add true to get urls ending in /
  trailingSlash: false,
  // Change to make the base url of the site different, by default https://{website}.com/docs,
  // changing to /company would be https://{website}.com/company/docs,
  base: "/",
  // Customize the logo, add your logo to public/ folder
  logo: {
    alt: "EventCatalog Logo",
    src: "/logo.png",
    text: "MetaRetail Inc",
  },
  docs: {
    sidebar: {
      // Should the sub heading be rendered in the docs sidebar?
      showPageHeadings: true,
    },
  },
  generators: [
    // Add single OpenAPI file to a domain
    [
      '@eventcatalog/generator-openapi',
      {
        services: [
          { 
            path: path.join(__dirname, 'openapi-files', 'orders-service.yml'),
            id: 'orders-service'
          }
        ],
        domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
        // Will render POST, GET, PUT, DELETE as badges in the sidebar
        sidebarBadgeType: 'HTTP_METHOD',
        // or set the license key via the environment variable as EVENTCATALOG_LICENSE_KEY_OPENAPI
        licenseKey: 'YOUR_LICENSE_KEY'
      },
    ],
    // Add multiple OpenAPI files to a domain
    [
      '@eventcatalog/generator-openapi',
      {
        services: [
          { 
            path: path.join(__dirname, 'openapi-files', 'payment-service.yml'),
            id: 'payment-service'
          },
          { 
            path: path.join(__dirname, 'openapi-files', 'fraud-detection-service.yml'),
            id: 'fraud-detection-service'
          }
        ],
        domain: { id: 'payment', name: 'Payment', version: '0.0.1' },
        // Will render QUERY, COMMAND, EVENT as badges in the sidebar
        sidebarBadgeType: 'MESSAGE_TYPE',
        // Here we map the HTTP methods to the message types for EventCatalog (optional)
        // e.g All post requests are mapped to commands, all get requests are mapped to queries
        httpMethodsToMessages: {
          GET: 'query',
          POST: 'command',
          PUT: 'command',
          DELETE: 'command',
        }
        // or set the license key via the environment variable as EVENTCATALOG_LICENSE_KEY_OPENAPI
        licenseKey: 'YOUR_LICENSE_KEY'
      },
    ],
  ],
};

You can view an example configuration in the EventCatalog OpenAPI plugin GitHub repository.

Need help?

If you have questions or need help, you can join our Discord community or refer to the OpenAPI examples on GitHub.