Skip to main content

Getting started

Added in eventcatalog@2.6.0
License: Dual-license

The OpenAPI specification is a widely-adopted standard for defining and describing RESTful APIs in a structured, machine-readable format. It provides a way to document APIs, including the endpoints, parameters, request and response formats, authentication methods, and more, making it easier for both humans and machines to understand and interact with the API.

Using the EventCatalog OpenAPI generator you can automate and generate your EventCatalog.

Core Features​

The EventCatalog OpenAPI plugin can provide you with many features:

How it works​

Example

EventCatalog supports generators. These are scripts or plugins that can be run to integrate with any external API, system or specification files. EventCatalog also provides an SDK to give developers easier access to their catalogs through custom scripts or generators.

The EventCatalog OpenAPI plugin let's you define 1 or many OpenAPI files. When running the generate command the scripts populate your EventCatalog. You can choose how your OpenAPI services are added to EventCatalog and which domain they belong to.

Getting started​

1. Install the plugin​

npm i @eventcatalog/generator-openapi

2. Configure your generator in your 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',
  // 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: 'OurLogix',
  },
  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' },
      },
    ],
    // Add many openapi files to a domain
    [
      '@eventcatalog/generator-openapi',
      {
        services: [
          { path: [path.join(__dirname, 'openapi-files', 'payment-service.yml'), id: 'payment-store' },
          { path: [path.join(__dirname, 'openapi-files', 'fraud-detection-service.yml'), id: 'fraud-detection-service' },
        ],
        domain: { id: 'payment', name: 'Payment', version: '0.0.1' },
      },
    ],
  ],
};

3. Run the generate command​

This command will run the generators in your eventcatalog.config.js file.

npm run generate

4. View your catalog​

Run your catalog locally to see the changes

npm run dev

Commercial Use​

This plugin is governed by a dual-license. To ensure the sustainability of the project, you can freely make use of this software if usage is also Open Source. Otherwise for proprietary use, internal use, and private modifications you must obtain a commercial license.

To purchase a license you to login to the EventCatalog Dashboard or if you have any questions you you can email us at hello@eventcatalog.dev.

Login to EventCatalog Dashboard