📦 plugin-generator-asyncapi
EventCatalog plugin to generate a catalog from your AsyncAPI files.
This plugin will generate Service and Event documents based on your AsyncAPI file.
Once setup run npm run generate
within your project.
How it works
The plugin will parse your AsyncAPI file looking for events and services and use this information for your catalog.
What if I already have events and services?
The plugin will check to see if the service or event already exists. If true
then the events will be versioned (based on your config) and services will be overriden (until service version is working).
If you already have configured markdown in your events or services, this markdown will be reused in your new generation. This means the content (documentation) of your events and services will be kept the same, but the metadata (frontmatter) will be updated (version, naming, summarys, links etc).
How is this plugin useful?
You may be a team that likes to be spec driven, so you can keep your spec up to date and continue to work on it and just run npm run generate
in the catalog to have the features from EventCatalog
.
You can use EventCatalog
with AsyncAPI
specs to enhance your documentation and use all the features of EventCatalog (3D node graphs, Diagrams, Documentation and much more...).
Installation
npm install --save @eventcatalog/plugin-doc-generator-asyncapi
Configuration
Name | Type | Default | Description |
---|---|---|---|
pathToSpec | string or string[] | '/asyncapi.yml' | Path or Paths to AsyncAPI documents. |
versionEvents | boolean | true | When the plugin runs and it finds matching events in the catalog, it will version the events before creating new documentation. |
externalAsyncAPIUrl | string | (empty) | When an AsyncAPI base url is set, an external link to the AsyncAPI message documentation will be added to each event. |
renderMermaidDiagram | boolean | true | When set to true, it will render the Mermaid diagrams to matched events from AsyncAPI file. |
renderNodeGraph | boolean | false | When set to true, it will render the NodeGraph diagram to the matched events from the AsyncAPI file. |
domainName | string | (empty) | The name of the Domain into which to place the events and services parsed from the AsyncAPI document(s). |
domainSummary | string | (empty) | Summary description of the domain. |
Example Configuration
Plugin Options
You will need to add the plugin into the generators
part of the eventcatalog.config.js
file.
const path = require('path');
module.exports = {
generators: [
[
'@eventcatalog/plugin-doc-generator-asyncapi',
{
// path to your AsyncAPI files
pathToSpec: [path.join(__dirname, 'asyncapi.yml')],
// version events if already in catalog (optional)
versionEvents: true
},
],
],
};
This will read the asyncapi.yml
file in the root of your project. You can provide whatever path you wish.
What if I want to parse AsyncAPI files into different domains?
If you want to specify several different domains into which different sets of AsyncAPI files should be parsed then you should use multiple AsyncAPI plugin instances in the generators
array where each generator listed with a domainName
will map to a unique domain into which the AsyncAPI file listed under the pathToSpec
property will be parsed.
const path = require('path');
module.exports = {
generators: [
// first generator pushes parsed files into the Orders domain
[
'@eventcatalog/plugin-doc-generator-asyncapi',
{
// path to your AsyncAPI files
pathToSpec: [path.join(__dirname, 'asyncapi-order-created.yml')],
// version events if already in catalog (optional)
versionEvents: true,
domainName: 'Orders'
},
],
// second generator pushes parsed files in the Payments domain
[
'@eventcatalog/plugin-doc-generator-asyncapi',
{
// path to your AsyncAPI files
pathToSpec: [path.join(__dirname, 'asyncapi-payments-processed.yml')],
// version events if already in catalog (optional)
versionEvents: true,
domainName: 'Payments'
},
],
],
};