Add support for API versioning

[ejsmith]

This pull request introduces comprehensive support for header-based API versioning in Foundatio.Mediator, updates the CleanArchitectureSample to demonstrate versioned endpoints, and adds benchmarking for endpoint performance with and without versioning. It also improves documentation to explain API versioning and adjusts sample URLs and port numbers for consistency.

API Versioning Support and Configuration

• Added support for header-based API versioning via ApiVersions and ApiVersionHeader in MediatorConfiguration at the assembly level, enabling Stripe-style version negotiation for endpoints. [1] [2] [3]
• Updated documentation to thoroughly explain API versioning concepts, usage patterns, handler annotations, and migration strategies. [1] [2]

Benchmarking and Sample Enhancements

• Introduced EndpointBenchmarks to compare manual, unversioned, and versioned endpoint performance using BenchmarkDotNet and Microsoft.AspNetCore.TestHost. [1] [2] [3]
• Updated the CleanArchitectureSample to:
  • Use new API versioning features in its configuration and endpoint mapping.
  • Refactor authentication and OpenAPI setup for modularity and clarity.

Documentation and Usability Improvements

• Expanded endpoint documentation to clarify handler group naming and versioning behaviors. (Fcb12f00L1)
• Updated sample URLs, ports, and HTTP request files to use the new port (5702) for consistency and clarity. [1] [2] [3] [4]

Project and Dependency Updates

• Changed the benchmark project to use the Microsoft.NET.Sdk.Web SDK and added necessary dependencies for ASP.NET Core testing. [1] [2]

[Copilot]

Pull request overview

Adds header-based API versioning to Foundatio.Mediator’s generated minimal API endpoints (Stripe-style version negotiation), updates the CleanArchitectureSample to demonstrate versioned endpoints + per-version OpenAPI docs, and introduces benchmarks/tests for versioning behavior and performance.

Changes:

• Introduces compile-time configuration (ApiVersions, ApiVersionHeader) and endpoint metadata to enable header-based version selection.
• Generates an ASP.NET Core matcher policy + ApiExplorer provider to disambiguate same-route endpoints by version and produce per-version OpenAPI docs.
• Adds integration/unit/generator tests, sample updates (URLs/ports, docs wiring), and endpoint benchmarks.

Reviewed changes

Copilot reviewed 47 out of 47 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
tests/Foundatio.Mediator.Tests/Integration/E2E_EndpointVersioningTests.cs	New end-to-end tests validating header-based version routing behavior.
tests/Foundatio.Mediator.Tests/Integration/E2E_EndpointTests.cs	New end-to-end tests validating baseline endpoint behavior + auth.
tests/Foundatio.Mediator.Tests/GeneratorTestBase.cs	Adds ASP.NET Core reference needed for generator tests.
tests/Foundatio.Mediator.Tests/Foundatio.Mediator.Tests.csproj	Adds ASP.NET Core testing dependency needed by new tests.
tests/Foundatio.Mediator.Tests/Fixtures/EndpointTestHandlers.cs	Adds fixture handlers/messages used by E2E endpoint tests (versioned/unversioned).
tests/Foundatio.Mediator.Tests/EndpointVersioningTests.cs	Adds source-generator tests for versioned endpoint generation semantics.
tests/Foundatio.Mediator.Tests/AssemblyAttributes.cs	Enables endpoint routing + API versioning defaults for the test assembly.
tests/Foundatio.Mediator.Tests/ApiVersionMatcherTests.cs	Adds unit tests for candidate selection logic across versions/fallback.
tests/Foundatio.Mediator.Tests/ApiVersionComparisonTests.cs	Adds unit tests for version comparison logic in ApiVersionContext.
src/Foundatio.Mediator/PublishInterceptorGenerator.cs	Refactors emitted code formatting (multi-line literals).
src/Foundatio.Mediator/Models/EndpointInfo.cs	Renames “Category” concepts to “Group” and adds version/deprecation fields.
src/Foundatio.Mediator/Models/EndpointDefaultsInfo.cs	Adds global API versioning defaults (ApiVersions, ApiVersionHeader).
src/Foundatio.Mediator/MediatorGenerator.cs	Plumbs endpoint defaults into module generator.
src/Foundatio.Mediator/InterceptsLocationGenerator.cs	Refactors emitted attribute source formatting.
src/Foundatio.Mediator/HandlerGenerator.cs	Avoids hint-name collisions by qualifying generated handler class names.
src/Foundatio.Mediator/HandlerAnalyzer.cs	Extracts group + versioning + deprecation metadata from attributes.
src/Foundatio.Mediator/FoundatioModuleGenerator.cs	Emits DI registration for matcher policy/context/OpenAPI provider when enabled.
src/Foundatio.Mediator/EndpointGenerator.cs	Core implementation: endpoint metadata, version-aware duplicate resolution, matcher policy + ApiExplorer provider generation.
src/Foundatio.Mediator/CrossAssemblyHandlerScanner.cs	Removes extra blank lines (formatting cleanup).
src/Foundatio.Mediator.Abstractions/MediatorConfigurationAttribute.cs	Adds assembly-level configuration for API versioning.
src/Foundatio.Mediator.Abstractions/IApiVersionContext.cs	Adds injectable API version context abstraction.
src/Foundatio.Mediator.Abstractions/HandlerEndpointGroupAttribute.cs	Adds parameterless ctor + version/deprecation options; makes Name optional.
src/Foundatio.Mediator.Abstractions/HandlerEndpointAttribute.cs	Adds method-level versioning + deprecation options.
src/Foundatio.Mediator.Abstractions/ApiVersionMetadata.cs	Adds endpoint metadata + winner resolution logic for version selection.
src/Foundatio.Mediator.Abstractions/ApiVersionContext.cs	Adds default implementation for version comparisons and access.
samples/CleanArchitectureSample/src/Web/vite.config.ts	Updates backend default port and removes SSE proxy entry.
samples/CleanArchitectureSample/src/Web/src/lib/stores/eventstream.svelte.ts	Updates SSE endpoint path to /api/events.
samples/CleanArchitectureSample/src/Web/src/lib/components/layout/Header.svelte	Updates Scalar docs link to /scalar.
samples/CleanArchitectureSample/src/Web/src/lib/api/client.ts	Adds default Api-Version header for sample frontend requests.
samples/CleanArchitectureSample/src/Web/.env.example	Updates default API base URL to new port.
samples/CleanArchitectureSample/src/Products.Module/Versions/2025_06_01/ProductMessages.cs	Adds version-specific product messages for sample API evolution.
samples/CleanArchitectureSample/src/Products.Module/Versions/2025_06_01/ProductHandler.cs	Adds version-specific product handler returning a simplified DTO.
samples/CleanArchitectureSample/src/Products.Module/Versions/2025_06_01/ProductDto.cs	Adds version-specific DTO for sample API evolution.
samples/CleanArchitectureSample/src/Products.Module/AssemblyAttributes.cs	Enables API versioning for the Products module assembly.
samples/CleanArchitectureSample/src/Api/WebApplicationExtensions.cs	Adds reusable OpenAPI + Scalar + demo auth wiring helpers.
samples/CleanArchitectureSample/src/Api/Properties/launchSettings.json	Updates ports to new values.
samples/CleanArchitectureSample/src/Api/Program.cs	Refactors auth/OpenAPI wiring and enables per-version OpenAPI docs.
samples/CleanArchitectureSample/src/Api/AssemblyAttributes.cs	Enables API versioning for the sample API assembly.
samples/CleanArchitectureSample/src/Api/Api.http	Updates default base URL port.
samples/CleanArchitectureSample/README.md	Updates sample docs (SSE URL + ports + API examples).
docs/guide/endpoints.md	Expands endpoint docs: group naming + comprehensive API versioning guide.
docs/guide/configuration.md	Documents new ApiVersions / ApiVersionHeader configuration options.
benchmarks/Foundatio.Mediator.Benchmarks/Program.cs	Adds entry point option to run endpoint benchmarks.
benchmarks/Foundatio.Mediator.Benchmarks/Handlers/Foundatio/EndpointHandlers.cs	Adds benchmark handlers for unversioned and versioned endpoint comparisons.
benchmarks/Foundatio.Mediator.Benchmarks/Foundatio.Mediator.Benchmarks.csproj	Switches to Web SDK and adds TestHost + dependency updates.
benchmarks/Foundatio.Mediator.Benchmarks/EndpointBenchmarks.cs	Adds BenchmarkDotNet tests comparing manual vs generated endpoints vs versioned endpoints.
benchmarks/Foundatio.Mediator.Benchmarks/AssemblyAttributes.cs	Enables endpoint discovery/prefix + API versioning for benchmark app.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.