@eventcatalog/core 3.35.0 → 3.36.1

package/dist/docs/plugins/apicurio/03-features.md

@@ -0,0 +1,221 @@
+---
+sidebar_position: 1
+keywords:
+- apicurio
+- features
+sidebar_label: Features
+title: Features
+description: Features of Apicurio Registry with EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+## Schema Version Management
+
+### Track All Schema Versions
+
+The Apicurio Registry plugin supports comprehensive schema version management through the `includeAllVersions` configuration option.
+
+When `includeAllVersions` is set to `true`, the plugin will:
+- Import all versions of each schema from your Apicurio Registry
+- Create versioned entries in EventCatalog for each schema version
+- Maintain version history for your schemas
+- Allow you to view and compare different versions
+
+When `includeAllVersions` is set to `false` (default):
+- Only the latest version of each schema is imported
+- This is useful for keeping your catalog focused on current schemas
+
+**Example:**
+
+```js
+{
+  registryUrl: 'http://localhost:8080',
+  includeAllVersions: true, // Import all versions
+}
+```
+
+**Use cases for version tracking:**
+- Understanding schema evolution over time
+- Maintaining backwards compatibility documentation
+- Tracking breaking changes in your schemas
+- Compliance and audit requirements
+
+### Adding Semantic Meaning to Schemas
+
+Using the Apicurio Registry plugin, you can import your schemas and then add business context and semantic meaning to them.
+
+When you import a schema into EventCatalog, an event, command, or query will be created with the schema attached. Each message has its own `index.mdx` file where you can add:
+- Title and summary
+- Detailed descriptions
+- Business context and use cases
+- Custom components and visualizations
+- Ownership and team information
+
+This gives you the opportunity to add meaning to your schemas and make them easier to understand for teams across your organization.
+
+**Important:** When you reimport your schemas, your semantic meaning will persist between imports. The plugin will:
+- Download the latest version of the schema from Apicurio Registry
+- Update the schema file in EventCatalog
+- Preserve your markdown documentation and business context
+
+## Integration with OpenAPI and AsyncAPI Generators
+
+One of the powerful features of the Apicurio Registry plugin is its ability to work with other EventCatalog generators.
+
+You can store OpenAPI and AsyncAPI specifications in your Apicurio Registry and use them to generate comprehensive service documentation automatically.
+
+:::info Plugin Licenses Required
+The OpenAPI and AsyncAPI generators are separate licensed plugins. You'll need to obtain license keys for each plugin you want to use from [EventCatalog Cloud](https://eventcatalog.cloud). A 14-day free trial is available for both plugins.
+
+See the [OpenAPI Plugin](/docs/plugins/openapi/intro) and [AsyncAPI Plugin](/docs/plugins/asyncapi/intro) documentation for more details on installation and configuration.
+:::
+
+### How it works
+
+1. Store your OpenAPI/AsyncAPI specifications in Apicurio Registry
+2. Configure the Apicurio plugin to attach these specifications to services
+3. Specify which EventCatalog generator should process each specification
+4. The plugin will fetch the specification and run the appropriate generator
+
+### Benefits
+
+- **Centralized Storage**: Keep all your schemas and specifications in one place (Apicurio Registry)
+- **Automated Documentation**: Generate service documentation from specifications automatically
+- **Consistent Workflow**: Use the same import process for schemas and specifications
+- **Domain Awareness**: Specifications inherit domain configuration from the Apicurio plugin
+
+### Example Configuration
+
+```js
+services: [{
+  id: 'Orders Service',
+  version: '1.0.0',
+  specifications: [
+    {
+      type: 'openapi',
+      artifactId: 'OrdersAPI-OPENAPI',
+      version: 'latest',
+      generator: ['@eventcatalog/generator-openapi', {
+        // OpenAPI generator options
+      }]
+    },
+    {
+      type: 'asyncapi',
+      artifactId: 'OrdersEvents-ASYNCAPI',
+      version: '2.0.0',
+      generator: ['@eventcatalog/generator-asyncapi', {
+        // AsyncAPI generator options
+      }]
+    }
+  ]
+}]
+```
+
+This configuration will:
+1. Fetch the OpenAPI specification from Apicurio Registry
+2. Save it to the service directory
+3. Run the OpenAPI generator to document REST endpoints
+4. Fetch the AsyncAPI specification
+5. Run the AsyncAPI generator to document async events
+6. All within the context of the Orders Service and its domain
+
+## Flexible Filtering System
+
+The Apicurio Registry plugin provides a powerful filtering system to control which schemas are assigned to services.
+
+### Filter Types
+
+- **Exact Matching**: Match schemas by exact artifact ID
+- **Prefix Matching**: Match schemas that start with a specific string
+- **Suffix Matching**: Match schemas that end with a specific string
+- **Includes Matching**: Match schemas that contain a specific string
+
+### Use Cases
+
+**Exact matching** is useful when you know the specific schemas a service interacts with:
+```js
+sends: [{ events: ['order-placed', 'order-cancelled'] }]
+```
+
+**Prefix matching** is useful for namespaced schemas:
+```js
+sends: [{ events: { prefix: 'order-' } }]
+// Matches: order-placed, order-cancelled, order-updated, etc.
+```
+
+**Suffix matching** is useful for schema naming conventions:
+```js
+receives: [{ commands: { suffix: '-command' } }]
+// Matches: place-order-command, cancel-order-command, etc.
+```
+
+**Includes matching** is useful for flexible pattern matching:
+```js
+receives: [{ events: { includes: 'inventory' } }]
+// Matches: inventory-updated, check-inventory, inventory-low, etc.
+```
+
+## Message Type Classification
+
+Document your schemas with semantic meaning by classifying them as:
+
+- **Events**: Things that have happened (past tense) - e.g., `order-placed`, `user-registered`
+- **Commands**: Requests to do something (imperative) - e.g., `place-order`, `cancel-order`
+- **Queries**: Requests for information - e.g., `get-order-status`, `find-user`
+
+This classification helps teams understand the intent and purpose of each message in your architecture.
+
+```js
+services: [{
+  id: 'Orders Service',
+  sends: [
+    { events: ['order-placed', 'order-cancelled'] }
+  ],
+  receives: [
+    { commands: ['place-order', 'cancel-order'] },
+    { queries: ['get-order-status'] }
+  ]
+}]
+```
+
+## Authentication Support
+
+<AddedIn version="0.1.0" />
+
+The Apicurio Registry plugin supports Bearer token authentication for secured registries.
+
+Simply set the `APICURIO_ACCESS_TOKEN` environment variable and the plugin will automatically include the Authorization header in all requests:
+
+```bash
+# .env file
+APICURIO_ACCESS_TOKEN=your-access-token-here
+```
+
+The plugin handles authentication transparently - all API requests will include the Bearer token when the environment variable is set.
+
+## Visualize Schemas, Services and Domains
+
+When you import your schemas into EventCatalog and assign them to services, you can use the EventCatalog Visualizer to see exactly how your schemas, services and domains are connected.
+
+The visualizer helps you:
+- Understand message flow between services
+- Identify dependencies and relationships
+- See your domain boundaries
+- Navigate your event-driven architecture visually
+
+## Downloading Schemas
+
+EventCatalog supports any schema format (Avro, JSON Schema, Protobuf, etc.). When you import your schemas from Apicurio Registry you can:
+- View the schema directly in EventCatalog
+- Download the schema for local development
+- See schema metadata and version information
+- Compare different versions of the same schema
+
+## Missing a Feature?
+
+If you are missing a feature, please let us know by opening an issue on [GitHub](https://github.com/event-catalog/eventcatalog/issues) or joining our [Discord community](https://eventcatalog.dev/discord).
+
+## Examples
+
+See the [eventcatalog-apicurio-example](https://github.com/event-catalog/generators/tree/main/examples/generator-apicurio) for working examples.

package/dist/docs/plugins/apicurio/04-examples.md

@@ -0,0 +1,20 @@
+---
+sidebar_position: 1
+keywords:
+- apicurio
+- examples
+sidebar_label: Examples
+title: Examples
+description: Examples of using the Apicurio Registry plugin
+---
+
+## Community Examples
+
+Have you created an example using the Apicurio Registry plugin? Share it with the community by opening a PR on [GitHub](https://github.com/event-catalog/generators) or sharing it in our [Discord community](https://eventcatalog.dev/discord).
+
+## Need Help?
+
+If you need help with any of these examples or have questions, please:
+- Join our [Discord community](https://eventcatalog.dev/discord)
+- Open an issue on [GitHub](https://github.com/event-catalog/eventcatalog/issues)
+- Check out the [plugin configuration documentation](/docs/plugins/apicurio/plugin-configuration)

package/dist/docs/plugins/apicurio/_category_.json

@@ -0,0 +1,12 @@
+{
+  "label": "Apicurio Registry Plugin",
+  "position": 6,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "apicurio",
+    "title": "Apicurio Registry",
+    "description": "Apicurio Registry integration for EventCatalog"
+  }
+}

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

@@ -0,0 +1,81 @@
+---
+sidebar_position: 1
+keywords:
+- components
+sidebar_label: Introduction
+title: Introduction
+description: Getting started with AsyncAPI plugin
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+import PluginLicense from '@site/src/components/MDX/PluginLicense';
+
+<AddedIn version="2.5.0"/>
+<PluginLicense url="#commercial-use" />
+
+<iframe width="100%" height="415" src="https://www.youtube.com/embed/XglwSNAnpKY?si=CtM_M0odLSPB8nhY" 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 folks building event-driven architectures are using and defining [AsyncAPI](https://www.asyncapi.com/en) files. The files are used to describe the service, it's messages it sends and receives and channels it uses to communicate.
+
+Using the EventCatalog AsyncAPI generator you can generate and maintain your EventCatalog.
+
+:::tip Try it now
+Want to see what your AsyncAPI file looks like in EventCatalog? [Try the playground](https://try.eventcatalog.dev) — drop your file and see the result in seconds.
+:::
+
+
+:::info
+**What is AsyncAPI?**: An industry standard for defining asynchronous APIs. Use this specification to document your service, channels and messages.
+:::
+
+### Core Features
+
+The EventCatalog AsyncAPI plugin can provide you with many features:
+
+- ⭐️ Generate domains, services and messages into your catalog from your AsyncAPI specification files
+- ⭐️ [Automate your EventCatalog and fetch AsyncAPI files by URL](/docs/plugins/asyncapi/features#fetch-asyncapi-files-by-url)
+- ⭐️ [Map commands, queries and events from your OpenAPI file using custom extensions](/docs/plugins/asyncapi/features#mapping-messages-events-commands-or-queries)
+- ⭐️ [Automatically version your changes in EventCatalog in sync with your AsyncAPI versions](#automatic-versioning)
+- ⭐️ [Allow you to write and persist custom markdown between changes](#persist-markdown)
+- ⭐️ [Display your message schemas in the catalog](#downloading-schemas)
+- ⭐️ [Fetch AsyncAPI files from any URL](#fetch-asyncapi-files-by-url)
+- ⭐️ Ability to download your message schemas and AsyncAPI files (also versioned)
+- ⭐️ Ability to draft services and endpoints in EventCatalog from your AsyncAPI files
+- ⭐️ and more....
+
+### How it works
+
+![Example](/img/integrations/asyncapi/asyncapi.jpeg)
+
+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 AsyncAPI plugin let's you define 1 or many AsyncAPI files. When running the generate command the scripts populate your eventcatalog. You can choose how your AsyncAPI services are added to EventCatalog and which domain they belong to.
+
+## 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. 
+
+See [pricing](/pricing) for more information.
+
+_Have any questions? You can email us at `hello@eventcatalog.dev`._
+
+## License FAQ
+
+### What is the license key for?
+The license key is required to use the OpenAPI 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.

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

@@ -0,0 +1,155 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog AsyncAPI
+sidebar_label: Installation
+title: Installation
+description: Installation of the EventCatalog AsyncAPI 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 AsyncAPI plugin is used to generate a catalog from an AsyncAPI specification files.
+
+You can map your AsyncAPI files to commands, events and queries in your catalog, and assign these to services and domains.
+
+## Installation
+
+Run the command below to install the EventCatalog AsyncAPI plugin.
+
+<Tabs>
+  <TabItem value="apple" label="Install on existing catalog" default>
+    ```bash
+npm i @eventcatalog/generator-asyncapi
+```
+  </TabItem>
+  <TabItem value="orange" label="Create new catalog with AsyncAPI plugin">
+     ```bash
+npx @eventcatalog/create-eventcatalog@latest my-catalog --template asyncapi
+```
+  </TabItem>
+</Tabs>
+
+#### Configuration
+
+Configure the plugin in your `eventcatalog.config.js` file.
+
+Add the plugin to the `generators` array.
+
+```js title="eventcatalog.config.js"
+// ...
+generators: [
+  // Add single AsyncAPI file to a domain
+  [
+    '@eventcatalog/generator-asyncapi',
+    {
+      services: [
+        { path: path.join(__dirname, 'asyncapi-files', 'orders-service.yml'), id: "Orders Service"}
+      ],
+      domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
+
+      // Run in debug mode, for extra output, if your AsyncAPI fails to parse, it will tell you why
+      debug: true
+    },
+  ],
+  // Add many AsyncAPI files to a domain
+  [
+    '@eventcatalog/generator-asyncapi',
+    {
+      services: [
+        // Add AsyncAPI file by URL
+        { path: "https://raw.githubusercontent.com/event-catalog/eventcatalog-asyncapi-example/refs/heads/main/asyncapi-files/payment-service.yml", id: "Payment Service"}
+        // Add AsyncAPI file using file system
+        { path: path.join(__dirname, 'asyncapi-files', 'fraud-detection-service.yml'), "Fraud Service"}
+      ],
+      domain: { id: 'payment', name: 'Payment', version: '0.0.1' },
+      // Run in debug mode, for extra output, if your AsyncAPI fails to parse, it will tell you why
+      debug: true
+    },
+  ],
+],
+};
+
+```
+
+### Configure license key
+
+The EventCatalog AsyncAPI plugin requires a license key to work with EventCatalog.
+
+You can get a trial license key from [EventCatalog Cloud](https://eventcatalog.cloud).
+
+You have a few options for setting the license key:
+
+1. [Setting license key in `.env` file (recommended)](#setting-license-key-in-env-file-recommended)
+2. [Setting license key in eventcatalog.config.js](#setting-license-key-in-eventcatalogconfigjs)
+
+#### 1. Setting license key in `.env` file (recommended)
+
+<AddedIn version="2.35.4" />
+
+Create a `.env` file in the root of your project and add the following:
+
+```bash title=".env"
+EVENTCATALOG_LICENSE_KEY_ASYNCAPI=your-license-key
+```
+
+:::tip Using an older version of EventCatalog?
+
+If you are using an older version of EventCatalog that does not support the `.env` file, you can just export the license key as an environment variable.
+
+```bash title="Setting license key in environment variables"
+export EVENTCATALOG_LICENSE_KEY_ASYNCAPI=your-license-key
+```
+
+:::
+
+#### 2. Setting license key in eventcatalog.config.js
+
+If you prefer, you can set the license key in the `eventcatalog.config.js` file
+using the `licenseKey` property in the EventCatalog AsyncAPI plugin.
+
+```js title="eventcatalog.config.js"
+export default {
+  generators: [
+    [
+      '@eventcatalog/generator-asyncapi',
+      {
+        licenseKey: '[INSERT_YOUR_LICENSE_KEY]', // or process.env.EVENTCATALOG_LICENSE_KEY_ASYNCAPI
+      },
+    ],
+  ],
+};
+```
+
+#### 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
+
+_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
+```
+
+## 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).
+
+
+