OpenAPI Output Caching Integration for xSDK

[danlorb]

OpenAPI Output Caching Integration for xSDK

🎯 Summary

• Goal: Implement configurable ASP.NET Core Output Caching for OpenAPI documents within the xSDK framework, controlled via the VariableService.
• Stack: ASP.NET Core 9.0/10.0, Microsoft.AspNetCore.OpenApi, Microsoft.AspNetCore.OutputCaching, xSDK VariableService

🛠 Roadmap (Pomodoro Tasks)

• Task 1: Schema Definition: Extend XsdkOptions or relevant Variable schema to include OpenApi.EnableCaching (Boolean, default: false) and OpenApi.CacheExpiration (Integer, seconds).
• Task 2: Service Registration: Update xSDK service collection extensions to conditionally call AddOutputCache() based on the VariableService state.
• Task 3: Middleware Injection: Inject UseOutputCache() into the xSDK request pipeline, ensuring it is placed after UseRouting() but before any OpenAPI endpoint mappings.
• Task 4: Conditional Endpoint Mapping: Modify the MapOpenApi call within xSDK to check the VariableService. If enabled, apply .CacheOutput() using the specialized OpenAPI caching policy.
• Task 5: Validation & Dev-Mode Check: Verify that the cache is inactive by default and remains inactive in local development environments unless explicitly toggled via configuration variables.

🔍 Acceptance Criteria

• Output Caching is disabled by default in all environments.
• Setting OpenApi.EnableCaching to true via VariableService enables caching for the generated OpenAPI JSON/YAML.
• The implementation uses the native Microsoft.AspNetCore.OpenApi caching extensions to ensure compatibility with ASP.NET Core 9/10 internals.
• Cache expiration is configurable via the VariableService.

⚠️ Constraints & Out-of-Scope

• This task only covers the OpenAPI document generation endpoint; general application-wide output caching for business API endpoints is out-of-scope for this phase.
• Distributed cache providers (Redis) are not part of this requirement; using the default In-Memory store.

💡 AI-Suggestions

• Bypass for Devs: Consider implementing a specific Cache-Control header check (e.g., no-cache) that allows developers to force a refresh even if caching is globally enabled.
• VaryByQuery: Ensure the cache policy accounts for different OpenAPI document names if multiple documents are hosted within the same xSDK instance.

📚 Resources

• ASP.NET Core OpenAPI Caching Docs
• xSDK VariableService Source
• Output Caching Middleware Ordering