Summary

Learn how EventCatalog's OpenAPI and AsyncAPI generators help companies bridge the gap between synchronous REST APIs and asynchronous event-driven architectures

Modern applications rarely live in isolation. They combine synchronous REST APIs for immediate operations with asynchronous messaging for resilient, scalable communication. But documenting this hybrid architecture presents unique challenges—until now.

EventCatalog's OpenAPI and AsyncAPI generators solve the critical problem of unified API documentation, helping companies bridge the gap between synchronous and asynchronous communication patterns in one cohesive catalog.

The documentation divide problem

Most companies today operate in a multi-API world:

• REST APIs handle immediate operations like user authentication, data retrieval, and real-time interactions
• Event-driven architectures manage background processing, system integration, and scalable communication

Yet these two worlds often exist in documentation silos. REST APIs get documented with tools like Swagger UI, while event schemas live in separate systems or wikis. This creates several critical problems:

Governance Gaps

Without unified documentation, teams struggle to maintain consistent naming conventions, schema standards, and ownership across sync and async APIs. What starts as minor inconsistencies grows into architectural debt.

Discovery Challenges

Developers waste time hunting across multiple tools to understand how systems communicate. Finding the right API endpoint or event schema becomes an archaeological expedition through scattered documentation.

Context Loss

When sync and async APIs are documented separately, teams lose sight of how they work together. The relationship between a REST API that triggers an event and the downstream services that consume it becomes invisible.

Ownership Confusion

Who owns which API? Which team maintains that event schema? Without centralized ownership tracking, accountability becomes fuzzy, leading to technical debt and governance failures.

How EventCatalog solves the unified API documentation challenge

EventCatalog's OpenAPI and AsyncAPI generators create a single source of truth for both synchronous and asynchronous APIs. Here's how it works:

Automatic API Discovery and Documentation

Both generators automatically parse your specification files and transform them into living documentation:

// eventcatalog.config.js
generators: [
  // OpenAPI Generator - Document your REST APIs
  [
    '@eventcatalog/generator-openapi',
    {
      services: [
        { path: './openapi/user-service.yml', id: 'user-service' },
        { path: './openapi/order-service.yml', id: 'order-service' },
      ],
      domain: { id: 'core', name: 'Core Services', version: '1.0.0' },
    },
  ],
  // AsyncAPI Generator - Document your event-driven APIs
  [
    '@eventcatalog/generator-asyncapi',
    {
      services: [
        { path: './asyncapi/payment-events.yml', id: 'payment-service' },
        { path: './asyncapi/inventory-events.yml', id: 'inventory-service' },
      ],
      domain: { id: 'commerce', name: 'Commerce', version: '1.0.0' },
    },
  ],
],

Unified Message Classification

EventCatalog bridges the conceptual gap between REST and messaging by classifying all operations as commands, queries, or events:

• OpenAPI operations can be mapped as commands or queries using the x-eventcatalog-message-type extension
• AsyncAPI messages can be classified using the same extension

# In your OpenAPI file
paths:
  /orders:
    post:
      summary: Create a new order
      x-eventcatalog-message-type: command
  /orders/{id}:
    get:
      summary: Get order details
      x-eventcatalog-message-type: query

# In your AsyncAPI file  
components:
  messages:
    OrderCreated:
      description: 'Event triggered when an order is created'
      x-eventcatalog-message-type: event

Cross-Domain Visualization

EventCatalog's visualizer shows how your REST APIs and events work together across domain boundaries, making it easy to spot integration points and dependencies.

View the demo

Automatic Versioning and Schema Management

Both generators automatically track API versions and schemas:

• REST API changes in OpenAPI specs trigger new service and message versions
• Event schema evolution in AsyncAPI files creates versioned event documentation
• Schemas are downloadable for both REST payloads and event structures

The value of unified API documentation

Faster Developer Onboarding

New team members can explore your entire API landscape—both sync and async—in one place. No more bouncing between Swagger docs, wiki pages, and Confluence to understand how systems communicate.

Improved Governance

Centralized ownership tracking, consistent naming conventions, and unified schema standards reduce architectural debt and improve system maintainability.

Better System Understanding

Teams can see the complete communication flow: how a REST API call triggers events, which services consume those events, and how data flows through your architecture.

Reduced Documentation Overhead

Instead of maintaining separate documentation systems, teams can generate comprehensive API docs directly from their specification files, keeping documentation in sync with code.

Getting started: From specifications to documentation

1. Prepare Your Specification Files

Ensure your OpenAPI and AsyncAPI files include the EventCatalog extensions for better message classification and ownership.

2. Configure the Generators

Add both generators to your EventCatalog configuration, pointing to your local files or remote URLs.

3. Run the Generation

Execute npx eventcatalog generate to automatically populate your catalog with both sync and async APIs.

4. Enhance with Context

Add custom markdown, diagrams, and business context to your generated documentation. EventCatalog preserves your additions across regenerations.

Ready to get started?

You can try both generators with a 30-day free trial. Visit EventCatalog Cloud to get your license key and start documenting your APIs today.

Key features that drive adoption

Flexible URL Support

Both generators can pull specification files from local filesystem or remote URLs, integrating seamlessly with your CI/CD pipeline.

Custom Extensions

EventCatalog-specific extensions let you define message ownership, versioning, and relationships beyond what standard specifications support.

Persistent Documentation

Your custom markdown and business context persists across generator runs, so you never lose the valuable context you've added.

Interactive Visualizations

Explore your API landscape through interactive diagrams that show relationships, dependencies, and data flow.

The future of API documentation is unified

The days of maintaining separate documentation for REST APIs and event-driven architectures are ending. Companies that adopt unified API documentation gain significant advantages in developer productivity, system governance, and architectural understanding.

EventCatalog's OpenAPI and AsyncAPI generators provide the foundation for this unified approach, helping teams bridge the gap between synchronous and asynchronous communication patterns.

Whether you're building microservices, implementing event-driven architectures, or managing hybrid systems, unified API documentation isn't just a nice-to-have—it's becoming a competitive necessity.

If you have any questions or want to join our community of over 1,200 people exploring EventCatalog and event-driven architecture, feel free to join us on Discord!