@eventcatalog/core 3.35.0 → 3.36.1

package/dist/docs/development/guides/services/adding-to-services/05-asyncapi.md

@@ -0,0 +1,97 @@
+---
+keywords:
+- EventCatalog domains
+sidebar_label: AsyncAPI specifications
+title: Adding AsyncAPI specifications
+description: Attach an AsyncAPI specification to your service and render them in your documentation
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<AddedIn version="2.6.0" />
+
+Services in EventCatalog allow you to render AsyncAPI specifications ([see demo](https://demo.eventcatalog.dev/docs/services/OrdersService/0.0.3/asyncapi/order-service-asyncapi)).
+
+![Example](../../img/services/asyncapi-spec.png)
+
+You have two options for adding AsyncAPI specifications to your service:
+
+- [Adding AsyncAPI files to EventCatalog](#adding-asyncapi-specifications-to-eventcatalog)
+- [Reference the AsyncAPI file from a remote URL](#reference-the-asyncapi-file-from-a-remote-url)
+
+:::tip Why not automate your EventCatalog from your AsyncAPI files?
+  Did you know you can automate your documentation, visualizations and owners using your AsyncAPI Files?
+
+  We have a [AsyncAPI plugin](/docs/plugins/asyncapi/intro) that can generate your catalog from your AsyncAPI files, transforming your operations into commands, queries and events. You can assign these to services and domains and much more...
+:::
+
+## Adding AsyncAPI files to EventCatalog
+
+This option is useful if you want to keep your AsyncAPI files in your EventCatalog.
+
+To add an AsyncAPI file to your service you will need to include the file itself inside the service directory.
+
+- `/services/{Service Name}/asyncapi.yml` 
+  - (example `/services/Orders/asyncapi.yml`)
+
+Then you need to reference the file in the service frontmatter.
+
+```md title="example: /services/Orders/index.mdx"
+---
+  specifications:
+    - type: asyncapi
+      # Path to the OpenAPI file relative to the service directory
+      path: asyncapi.yml
+      # Friendly name for the specification
+      name: AsyncAPI Specification
+---
+```  
+
+## Reference the AsyncAPI file from a remote URL
+
+<AddedIn version="2.61.2" />
+
+This can be useful if you want to keep your AsyncAPI files in a remote repository and render them in EventCatalog.
+
+The pages will be built at build time, so the URL needs to be accessible by the build machine.
+
+If your specifications changes you need to rebuild your EventCatalog as the pages are built at build time.
+
+```md title="example: /services/Orders/index.mdx"
+---
+  specifications:
+    - type: asyncapi
+      # Path to the OpenAPI file from a remote URL (accessible by the build machine)
+      path: https://raw.githubusercontent.com/event-catalog/generator-asyncapi/refs/heads/main/examples/product-api/asyncapi.yml
+      # Friendly name for the specification
+      name: Product API
+---
+```
+
+## Multiple AsyncAPI Files
+
+<AddedIn version="2.39.1" />
+
+You can also assign multiple AsyncAPI files to a single service.
+
+This can be useful if your service exposes multiple APIs or versions of the same API.
+
+```mdx title="example: /services/Orders/index.mdx"
+---
+  specifications:
+    - type: asyncapi
+      path: asyncapi-v1.yml
+      name: v1
+    - type: asyncapi
+      path: asyncapi-v2.yml
+      name: v2
+---
+```
+
+This will render a list of specification files on your service page and navigation bar.
+
+
+
+

package/dist/docs/development/guides/services/adding-to-services/06-graphql.md

@@ -0,0 +1,96 @@
+---
+keywords:
+- EventCatalog domains
+sidebar_label: GraphQL schemas
+title: Adding GraphQL schemas
+description: Add a GraphQL schema to your service and render them in your documentation
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<AddedIn version="2.6.0" />
+
+Services in EventCatalog allow you to render GraphQL schemas ([see demo](https://demo.eventcatalog.dev/docs/services/BillingService/0.0.1/graphql/schema)).
+
+![Example](../../img/services/graphql-spec.png)
+
+You have two options for adding GraphQL schemas to your service:
+
+- [Adding GraphQL files to EventCatalog](#adding-graphql-files-to-eventcatalog)
+- [Reference the GraphQL file from a remote URL](#reference-the-graphql-file-from-a-remote-url)
+
+:::tip Why not automate your EventCatalog from your GraphQL files?
+  Did you know you can automate your documentation, visualizations and owners using your GraphQL Files?
+
+  We have a [GraphQL plugin](/docs/plugins/graphql/intro) that can generate your catalog from your GraphQL files, transforming your operations into commands, queries and events. You can assign these to services and domains and much more...
+:::
+
+## Adding GraphQL files to EventCatalog
+
+This option is useful if you want to keep your GraphQL files in your EventCatalog.
+
+To add a GraphQL schema to your service you will need to include the file itself inside the service directory.
+
+- `/services/{Service Name}/graphql.schema` 
+  - (example `/services/Orders/graphql.schema`)
+
+Then you need to reference the file in the service frontmatter.
+
+```md title="example: /services/Orders/index.mdx"
+---
+  specifications:
+    - type: graphql
+      # Path to the OpenAPI file relative to the service directory
+      path: graphql.schema
+      # Friendly name for the specification
+      name: GraphQL Specification
+---
+```  
+
+## Reference the GraphQL file from a remote URL
+
+<AddedIn version="2.61.2" />
+
+This can be useful if you want to keep your GraphQL files in a remote repository and render them in EventCatalog.
+
+The pages will be built at build time, so the URL needs to be accessible by the build machine.
+
+If your schemas changes you need to rebuild your EventCatalog as the pages are built at build time.
+
+```md title="example: /services/Orders/index.mdx"
+---
+  specifications:
+    - type: graphql
+      # Path to the OpenAPI file from a remote URL (accessible by the build machine)
+      path: https://raw.githubusercontent.com/event-catalog/generator-graphql/refs/heads/main/examples/product-api/graphql.schema
+      # Friendly name for the specification
+      name: Product API
+---
+```
+
+## Multiple GraphQL Files
+
+<AddedIn version="2.39.1" />
+
+You can also assign multiple GraphQL files to a single service.
+
+This can be useful if your service exposes multiple APIs or versions of the same API.
+
+```mdx title="example: /services/Orders/index.mdx"
+---
+  specifications:
+    - type: graphql
+      path: graphql-v1.schema
+      name: v1
+    - type: graphql
+      path: graphql-v2.schema
+      name: v2
+---
+```
+
+This will render a list of schema files on your service page and navigation bar.
+
+
+

package/dist/docs/development/guides/services/adding-to-services/_category_.json

@@ -0,0 +1,10 @@
+{
+  "label": "Adding to services",
+  "position": 3,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/adding-to-services"
+  }
+}

package/dist/docs/development/guides/services/ownership-and-components/01-owners.md

@@ -0,0 +1,41 @@
+---
+sidebar_position: 8
+keywords:
+- EventCatalog
+- services 
+- owners
+sidebar_label: Owners
+title: Adding service owners
+description: Adding owners to services with EventCatalog.
+---
+
+Owners in EventCatalog are either **users** or **teams** and are **optional**.
+
+To add an owner or a team, you need to add the user or team to the owners field of the service.
+
+## Adding owners using frontmatter
+
+To add owners within a service you need to add them to the `owners` array within your service frontmatter API.
+
+You need to add the `id` of the owner.
+
+```md title="/services/OrderService/index.mdx (example)"
+---
+id: OrderService
+... # other service frontmatter
+owners:
+    - dboyne # represents a user
+    - webTeam # represents a team
+---
+
+<!-- Markdown contents... -->
+
+```
+
+Assigning owners to your services can provide others with context of who owns this service and how to contact them.
+
+:::tip Creating users and teams
+    EventCatalog gives you the ability to create users and teams. You can read the documentation to get started.
+:::
+
+

package/dist/docs/development/guides/services/ownership-and-components/02-components.md

@@ -0,0 +1,13 @@
+---
+sidebar_position: 8
+keywords:
+    - components 
+    - domains
+sidebar_label: Components
+title: Components
+description: Component list for domains 
+---
+
+You can add custom EventCatalog components to your services.
+
+[See the list of components and how to use them](/docs/development/components/using-components).

package/dist/docs/development/guides/services/ownership-and-components/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Ownership & components",
+  "position": 3,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/ownership-and-components",
+    "description": "A collection of guides to help you understand entities and how they work with EventCatalog."
+  }
+}

package/dist/docs/development/guides/services/versioning-and-lifecycle/01-versioning.md

@@ -0,0 +1,27 @@
+---
+keywords:
+- versioning
+- services
+sidebar_label: Versioning
+title: Versioning
+description: Learn how to version services
+---
+
+All content in EventCatalog can be versioned. This allows you to keep historic versions of content which can give context to users why things are changing.
+
+## How to version a service
+
+1. Create a `/versioned` directory inside the `/services` folder if one is not created already.
+1. Create a new folder with the version number inside the folder.
+    - Example: `/services/Orders/versioned/0.0.1`
+1. Copy contents into the new folder, it at least needs your index.mdx file.
+    - Example: `/services/Orders/versioned/0.0.1/index.mdx`
+    - Note: the version inside this index.mdx file would be `0.0.1`
+1. Bump the version of the `index.mdx` file in the route of the domain.
+    - Example `/services/Orders/index.mdx`, change the `version` to `0.0.2`
+
+## How to navigate to versions
+
+EventCatalog will automatically create links for you within your latest version of your document. Users will also be able to navigate to any version by adding the version in the url (e.g /docs/services/Orders/1.0.2 would load the 1.0.2 version of this service).
+
+![Example](../../img/domains/versioned.png)

package/dist/docs/development/guides/services/versioning-and-lifecycle/02-changelog.md

@@ -0,0 +1,52 @@
+---
+keywords:
+    - changelog 
+    - services
+sidebar_label: Adding a changelog
+title: Service changelogs 
+description: Adding changelogs to your services
+---
+
+EventCatalog supports changelogs for [domains](/docs/domains), [services](/docs/services) and [messages](/docs/messages).
+
+When you [version a service](/docs/development/guides/services/versioning-and-lifecycle/versioning) in EventCatalog, you can also attach a `changelog.mdx` to that service or versioned service.
+
+### Adding a changelog
+
+1. Add a `changelog.mdx` to your service (or versioned service)
+    - example `/services/{Service}/changelog.mdx`
+    - versioned example `/services/{Service}/versioned/1.0.0/changelog.mdx`
+
+**Example**
+```md title="/docs/services/PaymentService/changelog.md"
+---
+createdAt: 2024-08-01
+badges:
+    - content: New event published
+      backgroundColor: green
+      textColor: green
+---
+
+### Service now publishes a new event
+
+The PaymentService now publishes a new event called `PaymentAccepted`
+
+``` 
+
+Navigate to your change log page for your service (example [/docs/services/PaymentService/0.0.1/changelog](https://demo.eventcatalog.dev/docs/domains/Orders/0.0.2/changelog)) or **click on the Changelog button** on your service page.
+
+:::tip "What do add to your change log?"
+Changelogs are just markdown files, this allows you to add anything you want (e.g code blocks, tables)
+
+EventCatalog code blocks supports diffs, code labels which are great features for changelogs. You can [read more here](/docs/api/code-blocks).
+
+:::
+
+### Why add changelogs?
+
+Changelogs can provide your team with the context behind the reasons and choices for changes within your service and also be used for auditing purposes.
+
+Changelogs are visualized by EventCatalog.
+
+
+

package/dist/docs/development/guides/services/versioning-and-lifecycle/03-deprecating.md

@@ -0,0 +1,70 @@
+---
+keywords:
+- EventCatalog
+- services 
+- owners
+sidebar_label: Deprecating services
+title: Deprecating services
+description: Deprecating services with EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.33.10" />
+
+Any resource in EventCatalog can be deprecated or marked as deprecated.
+
+This will show a banner on the page indicating that the resource is deprecated.
+
+## Deprecating services using frontmatter
+
+To deprecate a service you need to add the `deprecated` field to the service frontmatter API.
+
+This accepts a `boolean` or an `object` with the following properties:
+
+- `date`: Date the service will be or was deprecated (YYYY-MM-DD)
+- `message`: Reason the service is deprecated, supports markdown (optional)
+
+```md title="/services/OrderService/index.mdx (example)"
+---
+id: OrderService
+... # other service frontmatter
+
+# deprecatd as an object (Recommended)
+deprecated:
+  # Date the service will be or was deprecated (YYYY-MM-DD)
+  date: 2025-01-01
+  # Reason the service is deprecated, supports markdown (optional)
+  message: | 
+    This service has been deprecated and replaced by the new service **InventoryServiceV2**.
+    Please contact the [team for more information](mailto:inventory-team@example.com) or visit our [website](https://eventcatalog.dev).
+
+# deprecated as a boolean 
+deprecated: true
+---
+
+```
+
+Configuration:
+
+- `deprecated`: `boolean` or `object`
+
+Deprecated as an object is recommended, as it gives your users more information to why the resource is deprecated and a date in the past or future.
+
+- `deprecated.date`: Date the service will be or was deprecated (YYYY-MM-DD)
+- `deprecated.message`: Reason the service is deprecated, supports markdown (optional)
+
+
+#### Rendered output
+
+Example of resource that will be deprecated:
+
+![Deprecating services](../../img/deprecated/will-be-deprecated.png) 
+
+Example of resource that is deprecated:
+
+![Deprecating services](../../img/deprecated/is-deprecated.png) 
+
+#### Demo
+
+You can see a demo of deprecating resources in the [EventCatalog demo site](https://demo.eventcatalog.dev/docs/services/InventoryService/0.0.2).

package/dist/docs/development/guides/services/versioning-and-lifecycle/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Versioning & lifecycle",
+  "position": 3,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/versioning-and-lifecycle",
+    "description": "A collection of guides to help you understand entities and how they work with EventCatalog."
+  }
+}

package/dist/docs/development/upgrading/_category_.json

@@ -0,0 +1,12 @@
+{
+  "label": "Upgrading",
+  "position": 13,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "starting-a-new-project/getting-started",
+    "title": "Starting a new project",
+    "description": "Learn how to install EventCatalog."
+  }
+}

package/dist/docs/development/upgrading/upgrading.md

@@ -0,0 +1,142 @@
+---
+sidebar_position: 1
+keywords:
+- Upgrade EventCatalog
+sidebar_label: Upgrading EventCatalog
+title: Upgrading EventCatalog
+description: How to upgrade EventCatalog.
+---
+
+## Upgrade to latest version
+
+To upgrade your EventCatalog to the latest version you can run the following command in your catalog directory.
+
+```bash
+npm install @eventcatalog/core@latest
+```
+
+### Manual upgrade
+
+To upgrade your EventCatalog you can find the packages `@eventcatalog/core` your `package.json` file.
+
+```json
+{
+  "name": "my-catalog",
+  "version": "0.0.1",
+  "private": true,
+  "scripts": {
+    ...
+  },
+  "dependencies": {
+    // Using "latest" will install the latest version of EventCatalog keeping you up to date
+    // or you can specify a specific version like "@eventcatalog/core": "2.4.0"
+    "@eventcatalog/core": "latest"
+  }
+}
+```
+
+Once you upgrade the version number, run `npm install` to install the latest updates.
+
+:::tip
+If you don't see the changes you expect, try removing the `.eventcatalog-core` folder, `node_modules` folder and install fresh again.
+:::
+
+### Having problems?
+
+Trying to upgrade and having issues? Try these steps
+
+1. Delete `node_modules` folder
+1. Delete `.eventcatalog-core` folder
+1. Delete `package-lock.json` (if you have one).
+1. Run `npm run i`
+1. Verify if issues are fixed
+
+Still having issues?
+  1. [Raise an issue on GitHub](https://github.com/event-catalog/eventcatalog) about your problems and how to replicate it.
+  1. Or join our [Discord](https://eventcatalog.dev/discord) and add your problem to the [Bugs channel](https://discord.com/channels/918092420338569216/1272467373042958377).
+
+## Upgrading from v1 to v2
+
+If you are upgrading from EventCatalog v1 to v2 you can follow the instructions below.
+
+<details>
+  <summary>Upgrading from v1 to v2</summary>
+  EventCatalog v2 comes with some small breaking changes to your EventCatalog.
+
+If you are using v1.x.x then this guide can help you.
+
+:::info Still want to use v1?
+
+**Still using v1 of EventCatalog?** V1 documentation can be found at https://v1.eventcatalog.dev/
+
+You can find the code for v1 on the branch https://github.com/event-catalog/eventcatalog/tree/v1
+
+We recommended to upgrade to v2 as support for v1 changes will be reduced.
+
+:::
+
+## Migrating to version 2
+
+EventCatalog v2 has been rewritten from the ground up. The easiest way to migrate to version 2 is following these steps:
+
+1. [Create a new Catalog](/docs/development/getting-started/installation)
+1. Delete the `domains`, `services`, `commands` and `events` folder.
+1. Copy your `eventcatalog.config.js` and `domains`, `services`, `events` folders into the new catalog.
+1. Add `ids` to all your resources ([read more](/docs/starting-a-new-project/getting-started#resources-now-require-ids))
+1. If your resource are in a nested structure [you need to flatten these out](/docs/starting-a-new-project/getting-started#resources-require-a-flat-structure).
+
+:::tip Having problems?
+If you are still having issues upgrading your catalog, [then please raise an issue on our GitHub repo.](https://github.com/event-catalog/eventcatalog/issues).
+:::
+
+
+## Resources now require ids
+
+**All domains, services and events need an id property in the frontmatter**. EventCatalog uses this `id` as the slug of the page and uses it as internal references.
+
+#### Example
+```md
+---
+# id is now required on all resources (domains, services and messages)
+id: order-service
+name: Order Service
+# rest of frontmatter..
+---
+<!-- Your markdown content -->
+```
+
+## Resources require a flat structure
+
+In EventCatalog v1 you could nest your resources for example have your events or services within your domains folder. (Example /domains/services/MyService/index.mdx)
+
+This feature is not currently supported in version 2.
+
+Version 2 requires your domains, services and messages (commands, and events) to be in the root directory.
+
+## Change to build output
+
+The build output has changed from v1 from being `out` directory to `dist` directory in version 2.
+
+## Customising your Catalog
+
+Customizing your catalog is not currently supported in v2, although this is on our roadmap (July 2024).
+
+## Generator plugins
+
+EventCatalog v1 supports generators (from EventBridge and AsyncAPI).
+
+EventCatalog v2 does not support these yet and are on the roadmap (July 2024).
+
+## Missing components
+
+Components from v1 has not yet been implemented. 
+
+- `<EventExamples/>` - Not currently supported, but you can use [AccordionGroup with code blocks](/docs/development/components/components/accordian-group)
+- `<SchemaExample />` - Not currently implemented - [Issue open](https://github.com/event-catalog/eventcatalog/issues/568)
+
+## Any other issues?
+
+If you have any issues or questions please [feel free to reach us on Discord](https://discord.com/invite/3rjaZMmrAm).
+
+</details>
+

package/dist/docs/development/upgrading/v2.md

@@ -0,0 +1,69 @@
+---
+sidebar_position: 3
+keywords:
+- Upgrade EventCatalog
+sidebar_label: v2 
+title: Upgrade to EventCatalog v2
+description: How to upgrade to EventCatalog v2.
+---
+
+This guide will help you upgrade from v1 to v2 of EventCatalog.
+
+EventCatalog v2 comes with some small breaking changes to your EventCatalog.
+
+:::info Still want to use v1?
+
+**Still using v1 of EventCatalog?** V1 documentation can be found at https://v1.eventcatalog.dev/
+
+You can find the code for v1 on the branch https://github.com/event-catalog/eventcatalog/tree/v1
+
+We recommended to upgrade to v2 as support for v1 changes will be reduced.
+
+:::
+
+## Migrating to version 2
+
+EventCatalog v2 has been rewritten from the ground up. The easiest way to migrate to version 2 is following these steps:
+
+1. [Create a new Catalog](/docs/development/getting-started/installation)
+1. Delete the `domains`, `services`, `commands` and `events` folder.
+1. Copy your `eventcatalog.config.js` and `domains`, `services`, `events` folders into the new catalog.
+1. Add `ids` to all your resources ([read more](/docs/starting-a-new-project/getting-started#resources-now-require-ids))
+1. If your resource are in a nested structure [you need to flatten these out](/docs/starting-a-new-project/getting-started#resources-require-a-flat-structure).
+
+:::tip Having problems?
+If you are still having issues upgrading your catalog, [then please raise an issue on our GitHub repo.](https://github.com/event-catalog/eventcatalog/issues).
+:::
+
+
+## Resources now require ids
+
+**All domains, services and events need an id property in the frontmatter**. EventCatalog uses this `id` as the slug of the page and uses it as internal references.
+
+#### Example
+```md
+---
+# id is now required on all resources (domains, services and messages)
+id: order-service
+name: Order Service
+# rest of frontmatter..
+---
+<!-- Your markdown content -->
+```
+
+## Resources require a flat structure
+
+In EventCatalog v1 you could nest your resources for example have your events or services within your domains folder. (Example /domains/services/MyService/index.mdx)
+
+This feature is not currently supported in version 2.
+
+Version 2 requires your domains, services and messages (commands, and events) to be in the root directory.
+
+## Change to build output
+
+The build output has changed from v1 from being `out` directory to `dist` directory in version 2.
+
+## Any other issues?
+
+If you have any issues or questions please [feel free to reach us on Discord](https://discord.com/invite/3rjaZMmrAm).
+