Skip to main content

Plugin Configuration

Overview

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

Required Configuration Options

OptionTypeRequiredDescription
servicesService[]YesList of OpenAPI files to add to your catalog
licenseKeystringYes*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:

PropertyTypeRequiredDescription
idstringYesEventCatalog ID for the service.
pathstring or string[]YesPath/s to your OpenAPI file or remote URL to the OpenAPI file. v6.0.0 introduced the ability to map multiple OpenAPI files to a single service.
ownersstring[]NoOwners of the service. You can assign EventCatalog users or teams to services.
setMessageOwnersToServiceOwnersbooleanNoIf true, the owners of the service will be set to the owners of the messages in the OpenAPI file (default is true).
generateMarkdownfunction-Function to override the default markdown generation for the service. See Markdown templates for more information.
draftbooleanNoIf true, the service will be drafted in EventCatalog with all it's endpoints / messages. (Added in v7.3.0)

Optional Configuration Options

OptionTypeDefaultDescription
domainobject-Domain to associate all configured services with
domain.idstring-Domain identifier
domain.namestring-Domain display name
domain.versionstring-Domain version
domain.draftbooleanNoIf true, the domain will be drafted in EventCatalog with all it's services / messages. (Added in v7.3.0)
domain.generateMarkdownfunction-Function to override the default markdown generation for the domain. See Markdown templates for more information.
messages.generateMarkdownfunction-Function to override the default markdown generation for the message. See Markdown templates for more information.
writeFilesToRootbooleanfalseWrite OpenAPI messages to root instead of service folder. By default all domains, services and messages will be grouped in the folder directory structure.
saveParsedSpecFilebooleanfalseParse and save expanded OpenAPI spec (helpful for files with $refs)
sidebarBadgeTypestringHTTP_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.
httpMethodsToMessagesobject-(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.
preserveExistingMessagesbooleantrue(Added in v5.0.5) If true, the existing message markdown is preserved on new generation (default is true). Setting to false will always write the message markdown from the OpenAPI spec file.

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.

Markdown templates

The EventCatalog OpenAPI plugin will generate default markdown for each domain, service and message.

If you want more control, you can override these using your own markdown templates.

To use your own markdown templates you need to provide a function that returns the markdown for the domain, service or message.

Below you can see examples of how to override the default markdown for the domain, service and message.

Domain

In this example we will override the default markdown for the domain using our custom function. We will also preserve the default markdown for the domain.

eventcatalog.config.js
// function to generate the markdown for the domain
// You can include this in your config file or in a separate file and import it
const generateMarkdownForDomain = ({ domain, markdown }) => {
return `# ${domain.name}
This is the default markdown for the domain

You can add anything you want here, including components, tables, etc.

## Architecture Diagram
<NodeGraph />

// Add the default markdown for the domain if you want to preserve it
${markdown}
`;
}

// Your configuration
export default {
generators: [
[
'@eventcatalog/generator-openapi',
{
// ...rest of generator config
domain: {
id: 'orders',
name: 'Orders',
version: '0.0.1',
generateMarkdown: generateMarkdownForDomain
}
}
]
]
}

Function Arguments:

ArgumentTypePropertiesDescription
domainobjectid, name, versionThe domain object you provided in the config
markdownstring-The default markdown for the domain. Incase you want to preserve the default markdown you can use this argument to add to your own markdown.

Need help?

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