One post tagged with "API Documentation"

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.

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!