2 posts tagged with "Documentation"

I'm excited to announce that EventCatalog now supports Attachments - a powerful new feature that allows you to link external resources, diagrams, and documentation directly to your domains, services, events, commands, queries, and channels.

Many teams and organizations have information scattered across different tools and platforms. This makes it difficult to find the information you need when you need it.

With Attachments, you can now link to external resources, diagrams, and documentation directly to your EventCatalog resources.

I'm excited to announce that EventCatalog 2.52.0 introduces a feature: the RemoteSchema component. This new component enables you to fetch and render schemas directly from remote URLs at runtime, ensuring your documentation stays synchronized with your live systems automatically.

For companies managing complex event-driven architectures, keeping documentation in sync with rapidly evolving APIs has always been a challenge. The RemoteSchema component solves this by creating a direct bridge between your live API definitions and your EventCatalog documentation.

Introducing the RemoteSchema Component​

The new RemoteSchema component gives you another way to add schemas into your documentation. Providing a URL to a schema will automatically fetch the schema and render it in your documentation.

Basic Usage​

---
id: UserRegistered
name: User Registered
---

The User Registered event is triggered when a new user signs up for our platform.

<!-- Fetch schema from public API -->
<RemoteSchema url="https://raw.githubusercontent.com/event-catalog/eventcatalog/refs/heads/main/examples/default/domains/E-Commerce/subdomains/Orders/services/InventoryService/events/InventoryAdjusted/schema.json" />

This simple addition automatically fetches and renders the latest schema from your API, ensuring the documentation always reflects the current state of your system.

Advanced Features​

Custom Authentication for Private APIs

For teams with private API endpoints, the component supports custom headers for authentication and environment variable mapping.

<RemoteSchema 
  url="https://private-api.example.com/schemas/order.json"
  headers={{
    "Authorization": "Bearer ${API_TOKEN}",
    "X-API-Key": "${API_KEY}"
  }}
  title="Order Schema"
/>

JSONPath Extraction

When working with large data sets you can extract specific schema definitions using JSONPath.

<RemoteSchema 
  url="https://api.example.com/openapi.json"
  jsonPath="$.components.schemas.UserEvent"
  title="User Event Schema"
/>

Environment Variable Support

Keep sensitive information secure using environment variables:

<RemoteSchema 
  url="https://${API_HOST}/schemas/payment.json"
  headers={{
    "Authorization": "Bearer ${API_TOKEN}"
  }}
/>

How can this help your team?​

1. Single Source of Truth​

The RemoteSchema component creates a direct connection between your live APIs and documentation. When schemas change in your API gateway, schema registry, or service endpoints, your documentation automatically reflects those changes without any manual intervention.

2. Sync your schemas without manual updates​

If you prefer to keep your schemas in a single source of truth, you can use the RemoteSchema component to fetch the schema from your API gateway, schema registry, or service endpoints. EventCatalog will automatically fetch the schema and render it in your documentation.

3. Improved Developer Experience​

New team members and API consumers can trust that the documentation accurately represents the current API state. This reduces confusion, speeds up onboarding, and improves overall developer productivity.

4. Enterprise-Ready Security​

With support for custom authentication headers and environment variables, the component works seamlessly with private APIs and enterprise security requirements.

How is this different to EventCatalog Plugins?​

EventCatalog provides a list of plugins that can fetch schemas from remote sources (e.g OpenAPI, AsyncAPI plugins, Confluent Schema Registry, AWS Glue Schema Registry, etc). Using these plugins you can do advanced mapping and filtering of your schemas to your services, domains and messages.

Next Steps​

The RemoteSchema component is available now in EventCatalog 2.52.0. To get started:

1. Upgrade your EventCatalog to the latest version
2. Read the full documentation for detailed usage examples
3. Join our Discord to share your use cases and get help from the community

This feature represents a significant step forward in making EventCatalog a living, breathing documentation platform that stays synchronized with your evolving architecture. By connecting directly to your live systems, EventCatalog becomes not just documentation, but a real-time reflection of your event-driven architecture.

The future of API documentation is dynamic, connected, and always current. The RemoteSchema is one step towards that future.