@eventcatalog/core 3.35.0 → 3.35.1

package/dist/docs/plugins/amazon-apigateway/02-plugin-configuration.md

@@ -0,0 +1,136 @@
+---
+sidebar_position: 1
+keywords:
+- Amazon API Gateway
+sidebar_label: Plugin Configuration
+title: Plugin Configuration
+description: Configuration of the Amazon API Gateway plugin
+---
+
+This plugin requires a license key. You can get a 14 day free trial license key by signing up to [EventCatalog Cloud](https://eventcatalog.dev/cloud).
+
+Once you have your license key you can set the `EVENTCATALOG_LICENSE_KEY_AMAZON_APIGATEWAY` environment variable.
+
+## Overview
+
+The Amazon API Gateway plugin is configured in the `eventcatalog.config.js` file inside the `generators` array.
+
+## Configuration Options
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `output` | string | No | `amazon-apigateway-specs` | The output directory for the OpenAPI specifications (used by the OpenAPI Generator plugin) |
+| `credentials` | [AwsCredentialIdentity](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-smithy-types/Interface/AwsCredentialIdentity/) | No | - | AWS credentials to use for the import on AWS. If this is not provided it will default to the credentials on the machine. |
+| `licenseKey` | string | No | - | You can either pass the license key directly or set the `EVENTCATALOG_LICENSE_KEY_AMAZON_APIGATEWAY` environment variable. |
+| `apis` | API[] | Yes | - | Array of API configurations |
+
+## API Configuration
+
+The `apis` option is an array of API configurations. Each API configuration has the following options:
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `name` | string | Yes | - | Name of the API in AWS |
+| `region` | string | Yes | - | AWS region of the API |
+| `stageName` | string | Yes | - | Stage name of the API |
+| `version` | number | No | 1 | Version of the API. Amazon API Gateway versions using dates. EventCatalog needs to use semver as versions. It will default to `1` but you can specify a different version. |
+| `routes` | Route | No | - | Map your routes into EventCatalog information. For example map your routes into commands, queries, events, etc. |
+
+## Route Configuration
+
+The `routes` option is a map of routes. Each route has the following options:
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `type` | string | Yes | - | Type of the route. Can be `command`, `query`, or `event`. |
+| `id` | string | No | - | EventCatalog ID, if you want to override it. |
+| `name` | string | No | - | Give the message (route) a name in EventCatalog |
+| `description` | string | No | - | Define a description for the message |
+
+## Example Configuration
+
+```js title="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: "EventCatalog",
+  tagline: "Discover, Explore and Document your Event Driven Architectures",
+  organizationName: "Your Company",
+  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: "EventCatalog",
+  },
+  docs: {
+    sidebar: {
+      // Should the sub heading be rendered in the docs sidebar?
+      showPageHeadings: true,
+    },
+  },
+  generators: [
+    [
+      "@eventcatalog/generator-amazon-apigateway",
+      {
+        output: 'amazon-api-gateway-output',
+        apis: [
+          {
+            // The name of the API we want to process
+            name: 'EcommerceApi',
+            // Assume it's deployed to us-east-1, change this if you deployed somewhere else
+            region: 'us-east-1',
+            // The API stage name
+            stageName: 'prod',
+            version: '2',
+            // Optional routes, we can map routes to message types
+            // give them descriptions and unique ids in eventcatalog
+            routes: {
+              'post /cart/checkout': {
+                type: 'command',
+                id: 'CheckoutCart',
+                description: 'Request to checkout the cart',
+              },
+              'post /cart/clear': {
+                type: 'command',
+                id: 'ClearCart',
+                description: 'Request to clear the cart',
+              },
+            }
+          }
+        ]
+      },
+    ],
+    // This will process the output of the amazon api gateway generator
+    // it will process the OpenAPI file and map it into a service and domain
+    // All routes are mapped to messages.
+    [
+      "@eventcatalog/generator-openapi",
+      {
+        services: [
+          { path: path.join(__dirname, "amazon-api-gateway-output", "EcommerceApi.json"), id: 'ecommerce-api', owners: ['full-stack'] },
+        ]
+      },
+    ],
+  ],
+};
+```
+
+You can view an example configuration in the  [EventCatalog Amazon API Gateway plugin GitHub repository](https://github.com/event-catalog/generators/blob/main/examples/generator-amazon-apigateway/basic/eventcatalog.config.js).
+
+
+
+
+
+

package/dist/docs/plugins/amazon-apigateway/03-features.md

@@ -0,0 +1,71 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Features
+title: Features
+description: Features of AsyncAPI with EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+### Customize the output directory
+
+The plugin will output the OpenAPI specification to the directory you specify in the `output` property.
+
+```js title="eventcatalog.config.js"  
+output: 'amazon-api-gateway-output',
+```
+
+By default the plugin will output to `amazon-api-gateway-output` in the root of your project.
+
+Remember to add the output directory to your `.gitignore` file so it's not checked into your repository.
+
+### Map routes to messages in EventCatalog
+
+The API Gateway plugin maps routes to messages in EventCatalog. You can map your routes to queries, commands or events.
+
+To map routes you can use the `apis` property in the plugin configuration.
+
+```js title="eventcatalog.config.js"  
+generators: [
+    [
+      "@eventcatalog/generator-amazon-apigateway",
+      {
+        output: 'amazon-api-gateway-output',
+        apis: [
+          {
+            // The name of the API we want to process
+            name: 'EcommerceApi',
+            // Assume it's deployed to us-east-1, change this if you deployed somewhere else
+            region: 'us-east-1',
+            // The API stage name
+            stageName: 'prod',
+            version: '2',
+            // Optional routes, we can map routes to message types
+            // give them descriptions and unique ids in eventcatalog
+            routes: {
+              'post /cart/checkout': {
+                type: 'command',
+                id: 'CheckoutCart',
+                description: 'Request to checkout the cart',
+              },
+              'post /cart/clear': {
+                type: 'command',
+                id: 'ClearCart',
+                description: 'Request to clear the cart',
+              },
+            }
+          }
+        ]
+      },
+    ],
+  ],
+```
+
+In the example above we are mapping the `post /cart/checkout` and `post /cart/clear` routes to commands in EventCatalog. When we run the plugin new messages called `CheckoutCart` and `ClearCart` will be created in EventCatalog.
+
+We can also specify the `id` and `description` for the message if we choose to override the default values. The values are taken from the operationId in the OpenAPI specification.
+
+
+

package/dist/docs/plugins/amazon-apigateway/04-examples.md

@@ -0,0 +1,15 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Examples
+title: Examples
+description: Examples of using the Amazon API Gateway plugin
+---
+
+You can find many examples of using the Amazon API Gateway plugin in the [EventCatalog GitHub repository](https://github.com/event-catalog/generators).
+
+## Examples
+
+- [Amazon API Gateway Example](https://github.com/event-catalog/generators/tree/main/examples/generator-amazon-apigateway/basic)
+  - Pull OpenAPI specifications from Amazon API Gateway and map to services, domains and messages. Use custom filters to map routes to services.

package/dist/docs/plugins/amazon-apigateway/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Amazon API Gateway Plugin",
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "amazon-apigateway",
+    "title": "Amazon API Gateway",
+    "description": "Amazon API Gateway integration documentation for EventCatalog"
+  }
+}

package/dist/docs/plugins/apicurio/00-intro.md

@@ -0,0 +1,102 @@
+---
+sidebar_position: 1
+keywords:
+- apicurio
+- schema registry
+sidebar_label: Introduction
+title: Introduction
+description: Getting started with Apicurio Registry plugin
+---
+
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+import PluginLicense from '@site/src/components/MDX/PluginLicense';
+
+<PluginLicense url="#commercial-use" />
+
+
+<iframe width="100%" height="415" src="https://www.youtube.com/embed/0DmGWa0sr6w?si=KsE4D9C_yN7998Vo" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
+
+
+---
+
+Many teams building event-driven architectures use schema registries to manage their message schemas and API specifications.
+
+[Apicurio Registry](https://www.apicur.io/registry/) is an open-source schema registry that provides a centralized location to store and manage schemas for your event-driven applications. It supports multiple schema formats including Avro, JSON Schema, Protobuf, AsyncAPI, and OpenAPI.
+
+We believe schema registries are a great foundation, but there's significant value in adding semantic meaning to your schemas, assigning them to services and domains, and creating comprehensive documentation around your architecture.
+
+The [EventCatalog Apicurio Registry plugin](https://github.com/event-catalog/generators/tree/main/packages/generator-apicurio) allows you to import your schemas and specifications from Apicurio Registry into EventCatalog. Keep your architecture documentation in sync with your registry while unlocking additional visualization and documentation capabilities.
+
+:::info
+**What is Apicurio Registry?**: An open-source schema registry for event-driven architectures. Use it to store and manage your event schemas and API specifications. Learn more at the [Apicurio website](https://www.apicur.io/registry/).
+:::
+
+### Core Features of the Apicurio Registry plugin
+
+The EventCatalog Apicurio Registry plugin provides you with many powerful features:
+
+- ⭐️ Import schemas and specifications from your Apicurio Registry into EventCatalog
+- ⭐️ Keep schemas in sync with your architecture documentation
+- ⭐️ Automatic versioning - as your schemas change they are versioned in EventCatalog alongside your documentation
+- ⭐️ Support for multiple schema formats (Avro, JSON Schema, Protobuf, AsyncAPI, OpenAPI)
+- ⭐️ Add semantic meaning (markdown) to your schemas - provide business context and added value
+- ⭐️ Use custom filters (prefix, suffix, exact matches) to select which schemas to import
+- ⭐️ Assign schemas to services and domains
+- ⭐️ Document your schemas as commands, events, or queries
+- ⭐️ Integrate with OpenAPI and AsyncAPI plugins to generate complete service documentation
+- ⭐️ Visualize your event-driven architecture with the [EventCatalog Visualizer](/features/visualization)
+- ⭐️ Download and view schemas directly in EventCatalog
+- ⭐️ Talk to your schemas, services, and domains with the [EventCatalog Chat](/features/ai-assistant)
+- ⭐️ Support for Bearer token authentication for secured registries
+- ⭐️ and more....
+
+### How it works
+
+1. Install the Apicurio Registry plugin
+1. Configure the plugin (schemas, services, domains, specifications)
+1. Run the plugin to import your schemas into EventCatalog
+1. View and deploy your catalog
+
+![Apicurio Registry plugin](./images/apicurio.png)
+
+**What are generators?**
+
+EventCatalog supports [generators](/docs/plugins/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](/docs/sdk) to give developers easier access to their catalogs through custom scripts or generators.
+
+The EventCatalog Apicurio Registry plugin is a generator. It will import your schemas and specifications from your Apicurio Registry into EventCatalog.
+
+## Commercial and License
+
+This plugin requires a license key to be used.
+
+You can get a 14 day trial license key to try the plugin out by going to [EventCatalog Cloud](https://eventcatalog.cloud).
+
+After the trial you can purchase a license to continue using this plugin, we have different plans to suit your organization based on where you are in your governance and documentation journey.
+
+See [pricing](/pricing) for more information.
+
+_Have any questions? You can email us at `hello@eventcatalog.dev`._
+
+## Need a demo?
+
+If you would like a demo of the plugin, please feel free to reach out to us and book a time to chat at hello@eventcatalog.dev.
+
+## License FAQ
+
+### What is the license key for?
+The license key is required to use the Apicurio Registry plugin with EventCatalog. It helps support ongoing development and maintenance of the plugin and project.
+
+### How do I get a license key?
+You can obtain a license key by visiting [EventCatalog Cloud](https://eventcatalog.cloud). New users can start with a 14-day free trial.
+
+### Terms
+- **Trial Period**: 14 days free trial no credit card required
+- **Support**: Discord community support (extra for priority support)
+
+After your trial period ends, you can purchase a full license through [EventCatalog Cloud](https://eventcatalog.cloud) to continue using the plugin.
+
+## Any questions or need help?
+
+If you have questions or need help, you can join our [Discord community](https://eventcatalog.dev/discord) or raise an issue on [GitHub](https://github.com/event-catalog/eventcatalog/issues).

package/dist/docs/plugins/apicurio/01-installation.md

@@ -0,0 +1,165 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog Apicurio Registry
+sidebar_label: Installation
+title: Installation
+description: Installation of the EventCatalog Apicurio Registry plugin
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import PluginLicense from '@site/src/components/MDX/PluginLicense';
+import Beta from '@site/src/components/MDX/Beta';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<PluginLicense url="#commercial-use" />
+
+The Apicurio Registry plugin is used to generate a catalog from an Apicurio Registry and import your schemas and specifications into EventCatalog.
+
+You can map your schemas from your Apicurio Registry to events, commands, or queries in your catalog, and assign these to services and domains.
+
+## Installation
+
+Run the command below to install the EventCatalog Apicurio Registry plugin.
+
+:::tip "Don't have an EventCatalog project yet?"
+If you don't have an EventCatalog project yet, you can follow the instructions in the [Getting Started](/docs/development/getting-started/installation) guide.
+:::
+
+```bash
+npm i @eventcatalog/generator-apicurio
+```
+
+<!-- <Tabs>
+  <TabItem value="apple" label="Install on existing catalog" default>
+    
+  </TabItem>
+  <TabItem value="orange" label="Create new catalog with Apicurio Registry plugin">
+     ```bash
+npx @eventcatalog/create-eventcatalog@latest my-catalog --template apicurio
+```
+  </TabItem>
+</Tabs> -->
+
+## Configuration
+
+To use the plugin you need to configure it in your `eventcatalog.config.js` file.
+
+Add the plugin to the `generators` array.
+
+<Tabs>
+  <TabItem value="apple" label="Import all schemas" default>
+
+  In this example we import all schemas from an Apicurio Registry into EventCatalog.
+
+  You can also create services and assign schemas to them, along with domains. [(see examples)](/docs/plugins/apicurio/plugin-configuration#example-configurations).
+
+
+    ```js title="eventcatalog.config.js"
+    // ...
+    generators: [
+      // 1. Import all schemas from an Apicurio Registry
+      [
+        '@eventcatalog/generator-apicurio',
+        {
+          // The URL of your Apicurio Registry
+          registryUrl: 'http://localhost:8080',
+          // Do you want to include all versions of a schema? (default: false)
+          includeAllVersions: true
+        },
+      ],
+    ];
+    ```
+  </TabItem>
+  <TabItem value="orange" label="Import schemas and assign them to services and domains">
+
+In this example we document services, assign schemas to them, and organize everything within a domain.
+
+We create an `orders` domain and an `Orders Service` that sends and receives messages.
+
+```js title="eventcatalog.config.js"
+// ...
+ [
+  '@eventcatalog/generator-apicurio',
+      {
+        // The URL of your Apicurio Registry
+        registryUrl: 'http://localhost:8080',
+        // The services to assign schemas to (optional)
+        services: [
+          {
+            id: 'Orders Service',
+            version: '1.0.0',
+            // the messages this service sends
+            // We use the prefix matching against the artifact name
+            sends: [
+              { events: { prefix: 'order-' } }
+            ],
+            // the messages this service receives
+            // We use the exact matching against the artifact name
+            receives: [
+              { commands: ['place-order', 'cancel-order'] }
+            ],
+          },
+        ],
+        domain: {
+          id: 'orders',
+          name: 'Orders',
+          version: '1.0.0',
+        }
+      },
+    ],
+```
+  </TabItem>
+</Tabs>
+
+### Configure API keys
+
+The EventCatalog Apicurio Registry plugin requires API keys in your environment variables.
+
+1. A license key for the Apicurio Registry plugin (14 days trial, at [EventCatalog Cloud](https://eventcatalog.cloud))
+2. Apicurio Registry access token (optional - only if your registry requires authentication)
+
+Create a `.env` file in the root, and add your keys to the project.
+
+```bash title=".env"
+# EventCatalog license key
+EVENTCATALOG_LICENSE_KEY_APICURIO_SCHEMA_REGISTRY=your-license-key
+
+# Apicurio Registry Bearer Token (optional - only if your registry requires authentication)
+APICURIO_ACCESS_TOKEN=your-access-token-here
+```
+
+#### White listing EventCatalog domains
+
+If you are behind a firewall you will need to white list the domain `https://api.eventcatalog.cloud` in your firewall. This is because the plugin needs to verify your license key.
+
+#### Run the plugin
+
+Run the plugin to import your schemas into EventCatalog.
+
+_This command will run the generators in your eventcatalog.config.js file._
+
+```
+npm run generate
+```
+
+#### View your catalog
+
+Run your catalog locally to see the changes
+
+```
+npm run dev
+```
+
+#### Build your catalog for production
+
+```
+npm run build
+```
+
+## Any questions or need help?
+
+If you get stuck, find an issue or need help, please raise an issue on [GitHub](https://github.com/event-catalog/eventcatalog/issues) or join our [Discord community](https://eventcatalog.dev/discord).
+
+You can also find some examples of the plugin in action in our examples repository: [eventcatalog/examples](https://github.com/event-catalog/generators/tree/main/examples/generator-apicurio).