Generator API

Overview

API for the EventCatalog OpenAPI generator.

Example eventcatalog.config.js file

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 {
  title: 'OurLogix',
  tagline: 'A comprehensive logistics and shipping management company',
  organizationName: 'OurLogix',
  homepageLink: 'https://eventcatalog.dev/',
  landingPage: '',
  editUrl: 'https://github.com/boyney123/eventcatalog-demo/edit/master',
  trailingSlash: false,
  base: '/',
  logo: {
    alt: 'EventCatalog Logo',
    src: '/logo.png',
    text: 'OurLogix',
  },
  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')] }
        ],
        domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
      },
    ],
    // Add many OpenAPI files to a domain
    [
      '@eventcatalog/generator-openapi',
      {
        services: [
          path: [path.join(__dirname, 'openapi-files', 'payment-service.yml'), path.join(__dirname, 'openapi-files', 'fraud-detection-service.yml')],
        ],
        domain: { id: 'payment', name: 'Payment', version: '0.0.1' },
      },
    ],
  ],
};

warning

When importing node modules into your eventcatalog.config.js file, you need to import the entire package.

import path from "path"; //work

import { join } from "path"; // will not work

This is currently a limitation and is being looked at. Any problems or issues feel free to raise a GitHub issue.

Required fields

services

• Type: Service[]

List of services to add, these are your OpenAPI files.

eventcatalog.config.js

[
  // Just one OpenAPI file
  "@eventcatalog/generator-openapi",
  {
    services: [
      { path: path.join(__dirname, "openapi-files", "payment-service.yml"), id: 'payment-service' }
    ],
    domain: { id: "payment", name: "Payment", version: "0.0.1" },
  },
  // Many OpenAPI files
  "@eventcatalog/generator-openapi",
  {
    services: [
      {
        path: path.join(__dirname, "openapi-files", "payment-service.yml"),
        id: 'payment-service'
      },
      {
        path.join(__dirname, "openapi-files", "fraud-detection-service.yml"),
        id: 'fraud-detection-service'
      }
    ],
    domain: { id: "payment", name: "Payment", version: "0.0.1" },
  }
];

Service properties

Property name	Required	Description
path	true	The path to your AsyncAPI file
id	required	Id of the service, this will also be used as the folder name of your service.

Optional fields

domain

The domain you want the OpenAPI file/s to be associated with in your catalog.

eventcatalog.config.js

[
  "@eventcatalog/generator-openapi",
  {
    // No domain
    services: [
      { path: path.join(__dirname, "openapi-files", "payment-service.yml") }
    ]
  },
  "@eventcatalog/generator-openapi",
  {
    services: [
      { path: path.join(__dirname, "openapi-files", "payment-service.yml") }
      { path: path.join(__dirname, "openapi-files", "fraud-detection-service.yml") }
    ],
    // Add to the payment domain
    domain: { id: "payment", name: "Payment", version: "0.0.1" },
  },
];

saveParsedSpecFile

Added in @eventcatalog/generator-openapi@2.1.2

By default your OpenAPI file will render in your catalog as you define it.

If you are using $refs, or having issues seeing your OpenAPI file in your catalog, then you can set this value to true.

saveParsedSpecFile is false by default.

Setting saveParsedSpecFile to true will use the OpenAPI parser under the hood to parse your Spec file. This parsed spec file will be written to your catalog.

eventcatalog.config.js

[
    '@eventcatalog/generator-asyncapi',
        {
            services: [
          { path: path.join(__dirname, "openapi-files", "payment-service.yml") }
          { path: path.join(__dirname, "openapi-files", "fraud-detection-service.yml") }
        ],
        saveParsedSpecFile: true,
        // Add to the payment domain
        domain: { id: 'payment', name: 'Payment', version: '0.0.1' },
    },
]

Upgrading to 2.0 generator

• folderName is no longer used from version 2.0. Please use id in the service.
• id is now required in the Service configuration