Koalesce.OpenAPI 0.1.0-alpha

🐨 Koalesce

Koalesce is a .NET library designed to merge multiple OpenAPI definitions into a unified document to enable seamless API Gateway integration and simplify frontend client generation for microservices-based architectures.

How It Works?

• Koalesce fetches OpenAPI definitions from the specified SourceOpenApiUrls.
• It then merges them using supported providers, generating a single schema at MergedOpenApiPath.
• The final Koalesced API definition is serialized and available in JSON or YAML format.

⚡ Features

• ✅ Coalesce multiple OpenAPI definitions into one unified schema.
• ✅ Fully configurable via appsettings.json.
• ✅ Aligns perfectly with API Gateways.
• ✅ Aligns perfectly with UI tools for interacting with API endpoints.
• ✅ Allows output a json or yaml merged document regardless the document type of the source APIs.
• ✅ Streamlines API client generation since it results in one unified schema.
• ✅ Extensible architecture to support new API aggregation strategies.

⚙️ Basic Configuration

• 💡Parameters listed with 🔺 are required.
• 💡The file extension [.json, .yaml] defined in MergedOpenApiPath will define the merged output format.
• 💡Koalesce respects the order of SourceOpenApiUrls. This affects how identical paths are handled based on the SkipIdenticalPaths setting.

{
  "Koalesce": {
    "SourceOpenApiUrls": [
      "https://api1.com/swagger/v1/swagger.json",
      "https://api2.com/swagger/v1/swagger.json"
    ],
    "MergedOpenApiPath": "/swagger/v1/apigateway.json",
    "Title": "My Koalesced API",
    "SkipIdenticalPaths": true,
    "ApiGatewayBaseUrl": "https://api-gateway.com:5000",
    "Cache": {
      "DisableCache": false,
      "AbsoluteExpirationSeconds": 86400,
      "SlidingExpirationSeconds": 300,
      "MinExpirationSeconds": 30
    }
  }
}

🛠️ Caching Configuration (Koalesce.Cache)

{
  "Koalesce": {
    "Title": "My Koalesced API",
    "SourceOpenApiUrls": [
      "https://api1.com/swagger/v1/swagger.json",
      "https://api2.com/swagger/v1/swagger.json"
    ],
    "MergedOpenApiPath": "/swagger/v1/apigateway.json",    
    "SkipIdenticalPaths": true,
    "ApiGatewayBaseUrl": "https://api-gateway.com",
    "Cache": {
      "DisableCache": false,
      "AbsoluteExpirationSeconds": 86400,
      "SlidingExpirationSeconds": 300,
      "MinExpirationSeconds": 30
    }
  }
}

📦 Installation

🟢 For OpenAPI

dotnet add package Koalesce.OpenAPI

⚙️ Package-specific Configuration

🔺 This configuration extends the basic settings. Ensure that your Koalesce section includes all required base options.

{
  "Koalesce": 
  {
    "OpenApiVersion": "3.0.1",
    "Title": "My Koalesced OpenAPI",
    "SourceOpenApiUrls": [
      "https://localhost:5001/swagger/v1/swagger.json",
      "https://localhost:5002/swagger/v1/swagger.json",
      "https://fakerestapi.azurewebsites.net/swagger/v1/swagger.json"
    ],
    "MergedOpenApiPath": "/swagger/v1/swagger.yaml"
  }
}

🛠️ Usage with .NET pipeline

1️⃣ Register Koalesce.[ForProvider()]

In Program.cs:

builder.Services.AddKoalesce()
  // Register Koalesce.OpenAPI provider
  .ForOpenAPI();

2️⃣ Enable Middleware

app.UseKoalesce();

🔥 Running an Application (using Swagger.UI)

• Start the application:

  dotnet run
  

• Access the Koalesced API via Swagger UI:

  https://localhost:[port]/swagger/index.html
  

• The merged OpenAPI definition should be available at:

  https://localhost:[port]/[MergedOpenApiPath]
  

📝 License & Contribution

Koalesce is licensed under the MIT License.
Contributions are welcome! Feel free to submit issues and PRs on GitHub.