Koalesce.OpenAPI 1.0.0-alpha.12

Koalesce

Koalesce is an open-source, lightweight and extensible library designed to merge multiple API definitions into a unified document.

Official packages are published exclusively to NuGet.org by the maintainer. Do not trust packages from unofficial sources.

How It Works

• Koalesce fetches API definitions from the specified Sources.
• It merges them using an available provider (e.g., Koalesce.OpenAPI), generating a single schema at MergedDocumentPath.
• The final Koalesced API definition is serialized and available in JSON or YAML format.

Key Features

• Merge Multiple APIs: Coalesce multiple API definitions into one unified schema.
• Conflict Resolution: Automatic schema renaming and path collision detection.
• Flexible Configuration: Configure via appsettings.json or Fluent API.
• Fail-Fast Validation: Validates URLs and paths at startup to prevent runtime errors.
• Gateway Integration: Works seamlessly with Ocelot, YARP, and other API Gateways.
• Configurable Caching: Fine-grained cache control with absolute/sliding expiration settings.
• Ease Client Generation: Streamlines API client generation (e.g., NSwag, Kiota) with a single unified schema.
• Format Agnostic Output: Output JSON or YAML regardless of source document format.
• Extensible Core: Designed to support future providers for other API specification formats.

Design Philosophy

Koalesce balances Developer Experience with architectural governance:

• Resilient by Default: If a microservice is down, Koalesce skips it without breaking your Gateway.
• Strict by Choice: Can be configured to fail on unreachable services or route collisions - useful for CI/CD pipelines.
• Purposefully Opinionated: Ensures merged definitions have clean, deterministic, and conflict-free naming.

Where Koalesce Shines

Koalesce is ideal for Backend-for-Frontend (BFF) patterns where external consumers need a unified API view.

• Frontend applications consuming an API Gateway.
• SDK generation with tools like NSwag/Kiota from a single unified schema.
• Third-party developer portals exposing your APIs.
• External API consumers needing consolidated documentation.

Quick Start

1. Register Koalesce

builder.Services.AddKoalesce(builder.Configuration)
    .ForOpenAPI();

2. Enable Middleware

app.UseKoalesce();

Configuration

Core Configuration (Koalesce)

Source Configuration

Caching Configuration

OpenAPI Provider Configuration

Configuration Examples

Aggregation Mode

{
  "Koalesce": {
    "Sources": [
      { "Url": "https://service1.com/swagger.json" },
      { "Url": "https://service2.com/swagger.json" }
    ],
    "MergedDocumentPath": "/swagger/v1/all-apis.json",
    "Title": "All APIs Documentation"
  }
}

Gateway Mode (With Caching)

{
  "Koalesce": {
    "Sources": [
      {
        "Url": "https://localhost:8001/swagger/v1/swagger.json",
        "VirtualPrefix": "/customers"
      },
      {
        "Url": "https://localhost:8002/swagger/v1/swagger.json",
        "VirtualPrefix": "/inventory"
      }
    ],
    "MergedDocumentPath": "/swagger/v1/apigateway.json",
    "Title": "API Gateway",
    "ApiGatewayBaseUrl": "https://localhost:5000", // <-----
    "Cache": {  // <-----
      "AbsoluteExpirationSeconds": 86400,
      "SlidingExpirationSeconds": 300
    }
  }
}

Mixed Sources (HTTP + Local Files)

Useful when merging live APIs with downloaded specifications from public APIs:

{
  "Koalesce": {
    "Sources": [
      { "Url": "https://localhost:8001/swagger/v1/swagger.json" },
      { "FilePath": "./specs/external-api.json" }
    ],
    "MergedDocumentPath": "/swagger/v1/merged.json",
    "Title": "Combined API Documentation"
  }
}

Note: File paths can be absolute or relative. Relative paths are resolved from the application's base directory.

Strict Mode

{
  "Koalesce": {
    "Sources": [
      { "Url": "https://localhost:8001/swagger/v1/swagger.json" },
      { "Url": "https://localhost:8002/swagger/v1/swagger.json" }
    ],
    "MergedDocumentPath": "/swagger/v1/apigateway.yaml",
    "Title": "API Gateway",
    "ApiGatewayBaseUrl": "https://localhost:5000",
    "FailOnServiceLoadError": true, // <-----
    "SkipIdenticalPaths": false     // <-----
  }
}

Security Schemas

Koalesce is non-opinionated about security - authentication and authorization are responsibilities of your APIs and Gateway.

• Operations with security in downstream APIs keep their security requirements
• Operations without security remain public
• Mixed public/private scenarios are supported naturally
• Each API's security scheme is preserved in the merged document

Conflict Resolution

Path Conflicts

Schema Name Conflicts

CLI Tool

Install globally to merge OpenAPI specs without hosting an app:

dotnet tool install --global Koalesce.OpenAPI.CLI --prerelease
koalesce --config ./appsettings.json --output ./gateway.yaml --verbose

Documentation & Links

• Full Documentation
• Sample Projects
• Changelog
• CLI Changelog
• Contributing

License

Koalesce is licensed under the MIT License.