Getting started
eventcatalog@2.6.0
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:
- ⭐️ Generate domains, services and messages into your catalog
- ⭐️ Automatically version your changes in EventCatalog in sync with your OpenAPI versions
- ⭐️ Allow you to write and persist custom markdown between changes
- ⭐️ Display your OpenAPI specification in EventCatalog
- ⭐️ Display your endpoints and parameters in the catalog
- ⭐️ Ability to download your schemas and OpenAPI files (also versioned)
- ⭐️ and more....
How it works
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
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',
{
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',
{
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' },
},
],
],
};
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 obtain a commercial license or have any questions you can email us at hello@eventcatalog.dev
.
Features
Mapping messages as commands and 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 events or commands (query support coming soon).
You can use the x-eventcatalog-message-type
to specify the type of message.
By default everything parsed by EventCatalog is a command, unless you specify with the x-eventcatalog-message-type extension.
paths:
/pets:
get:
summary: List all pets
operationId: listPets
tags:
- pets
x-eventcatalog-message-type: query # command or event (query support soon)
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
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.