Read the Docs | Edit the Docs | View Demo

Core Features

• 📃 Sync your message schemas to services and domains from your Apicurio Registry
• ⭐ Go beyond a schema registry. Add semantic meaning to your schemas, business logic and much more. Help your developers understand the message schemas and their relationships.
• 📊 Visualise services and messages in your architecture (demo)
• ⭐ Download your message schemas from EventCatalog (e.g Avro, Protobuf, JSON) (demo)
• 💅 Custom MDX components (read more)
• 🗄️ Auto versioning of your schemas in EventCatalog
• ⭐ Attach OpenAPI and AsyncAPI specifications to services and auto-generate message documentation
• ⭐ Discoverability feature (search, filter and more) (demo)
• ⭐ Support for Apicurio Registry V2 and V3
• ⭐ And much more...

How it works

EventCatalog is technology agnostic, meaning it can integrate with any schemas, specs or brokers.

EventCatalog supports generators.

Generators are scripts that run pre-build to generate content in your catalog. Generators can use the EventCatalog SDK.

With this Apicurio Registry plugin you can connect your schema registries to your catalog. You can map events and commands to your schemas and keep them in sync with your documentation.

This is done by defining your generators in your eventcatalog.config.js file.

...
generators: [
    // Basic example mapping schemas from Apicurio Registry to services
    [
      '@eventcatalog/generator-apicurio',
      {
        // The URL of your Apicurio Registry
        registryUrl: 'http://localhost:8080/apis/registry/v2',
        services: [
          // Maps the exact artifact IDs to the service
          // In this example the Orders Service will publish the order-created event and receive the order-updated event
          {
            id: 'Orders Service',
            version: '1.0.0',
            sends: [{ events: ["order-created"] }],
            receives: [{ events: ["order-updated"] }]
          },
          // Filter by message name using prefix/suffix
          {
            id: 'Inventory Service',
            version: '1.0.0',
            sends: [{ events: [{ prefix: "inventory-" }] }],
            receives: [{ events: [{ suffix: "-updated" }] }]
          },
        ],
        // All the services are assigned to this domain
        domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
      },
    ],
    // Example with OpenAPI and AsyncAPI specifications attached to services
    [
      '@eventcatalog/generator-apicurio',
      {
        registryUrl: 'http://localhost:8080/apis/registry/v2',
        services: [
          {
            id: 'Orders Service',
            version: '1.0.0',
            sends: [{ events: ["order-created"] }],
            // Attach specifications from Apicurio Registry
            specifications: [
              {
                type: 'openapi',
                artifactId: 'orders-service-openapi',
                // Optionally run a generator on the spec to create message documentation
                generator: ['@eventcatalog/generator-openapi', { debug: true }]
              },
              {
                type: 'asyncapi',
                artifactId: 'orders-service-asyncapi',
                generator: ['@eventcatalog/generator-asyncapi']
              }
            ]
          },
        ],
        domain: { id: 'orders', name: 'Orders', version: '0.0.1' },
      },
    ],
    // This example saves all schemas from the registry to EventCatalog without mapping to services or domains
    [
      '@eventcatalog/generator-apicurio',
      {
        registryUrl: 'http://localhost:8080/apis/registry/v2',
      },
    ],
    // Include all versions of schemas (not just the latest)
    [
      '@eventcatalog/generator-apicurio',
      {
        registryUrl: 'http://localhost:8080/apis/registry/v2',
        includeAllVersions: true,
      },
    ],
  ],
...

In the examples above we have different use cases for the generator:

1. Map schemas to events/commands and assign them to producers and consumers (services). Group services into a domain.
2. Attach OpenAPI and AsyncAPI specifications to services and optionally run generators to create message documentation.
3. Document all schemas from the registry without assigning them to services or domains.
4. Include all versions of schemas in EventCatalog, not just the latest.

Getting started

Installation and configuration

Make sure you are on the latest version of EventCatalog.

1. Install the package

npm install @eventcatalog/generator-apicurio

2. If you want to use OpenAPI or AsyncAPI generators with specifications, install them as well:

npm install @eventcatalog/generator-openapi @eventcatalog/generator-asyncapi

3. Configure your eventcatalog.config.js file

4. Set your license key. Create a .env file in the root of your project and add the following:

# From eventcatalog.cloud (14 day free trial)
EVENTCATALOG_LICENSE_KEY_APICURIO_SCHEMA_REGISTRY=

5. Run the generate command

npm run generate

6. See your new domains, services and messages, run

npm run dev

Configuration Options

| Option | Type | Required | Description | | -------------------- | ----------- | -------- | --------------------------------------------------------------------------------------------- | | registryUrl | string | Yes | URL of the Apicurio Registry (e.g., http://localhost:8080/apis/registry/v2) | | includeAllVersions | boolean | No | Include all versions of schemas in the catalog (default: false, only latest) | | services | Service[] | No | List of services to add to the catalog | | domain | Domain | No | Domain to add to the catalog and attach services to | | licenseKey | string | No | License key (can also be set via EVENTCATALOG_LICENSE_KEY_APICURIO_SCHEMA_REGISTRY env var) |

Service Configuration

| Option | Type | Description | | ---------------- | ------------------------ | ------------------------------------------------------ | | id | string | Service identifier | | name | string | Display name (defaults to id) | | version | string | Service version | | sends | Filter[] | Messages the service sends (events, commands, queries) | | receives | Filter[] | Messages the service receives | | specifications | ServiceSpecification[] | OpenAPI/AsyncAPI specs to attach | | summary | string | Service summary |

Filter Criteria

Filters support multiple matching strategies:

// Exact match
sends: [{ events: ['order-created', 'order-updated'] }];

// Prefix match
sends: [{ events: [{ prefix: 'order-' }] }];

// Suffix match
receives: [{ events: [{ suffix: '-created' }] }];

// Contains match
receives: [{ events: [{ includes: 'order' }] }];

Found a problem?

Raise a GitHub issue on this project, or contact us on our Discord server.

Commercial Use

This generator requires a license to be used with EventCatalog. You can get a 14 day free trial at https://eventcatalog.cloud or email us at [email protected].