Add WolverineFx.Http.AspVersioning — Asp.Versioning.Http integration

[knotekbr]

Add WolverineFx.Http.AspVersioning — Asp.Versioning.Http integration

Summary

A companion package that integrates Wolverine HTTP endpoints with the full Asp.Versioning.Http stack. It complements the existing native URL-segment versioning (UseApiVersioning()) for teams that need header / query / media-type readers, the rest of the Asp.Versioning feature set, or a predictable migration of an existing Asp.Versioning app.

// You configure Asp.Versioning yourself; the bridge delegates entirely to it.
builder.Services.AddApiVersioning(options => options.ReportApiVersions = true);

app.MapWolverineEndpoints(opts => opts.UseAspVersioning());

Endpoints keep using the usual [ApiVersion], [MapToApiVersion], [AdvertiseApiVersions], and [ApiVersionNeutral] attributes, with the same method-overrides-class precedence as native versioning.

What's in the diff

• New package src/Http/Wolverine.Http.AspVersioning (+ test project). The core is one IHttpPolicy that resolves the versioning attributes and attaches a shared ApiVersionSet / MapToApiVersion per route group at bootstrap. It adds no request-time code; matching, reporting, and errors are all delegated to Asp.Versioning.

• Minimal changes to Wolverine.Http (the only shipped code touched):

  Change	Why
  ApiVersionResolver.BuildResolutions reuse + generalized to IApiVersionProvider.Options	reuses the native attribute-resolution logic; behavior-identical for the native path (regression test added)
  HttpChain.RequiresApplicationServices (opt-in, default false)	versioned chains need the app's IServiceProvider on their RouteEndpointBuilder for the Asp.Versioning finalizer; the default leaves every existing chain functionally identical
  2× InternalsVisibleTo	expose internals to the new package + its tests

Decisions worth a look

• Parity-first design. The bridge is built to behave identically to a hand-written Asp.Versioning minimal API. A parity test tier registers vanilla /native/* endpoints beside their Wolverine /wolverine/* twins on one host and asserts identical routing, version-report headers, error status, sunset/advertised behavior, and OpenAPI document grouping.
• net10.0-only. Asp.Versioning.Http 10.x ships net10-only and can't be mixed with the 8.x line (breaking Abstractions changes). Native versioning stays net9/net10. The two net10-only projects are marked <Build Project="false" /> in the solution (same pattern as the Polecat sample) and covered by a dedicated CIHttpAspVersioning target, so the net9 solution build should be unaffected.
• Route-only grouping (verb-agnostic) and request-time conflict detection (deferred to Asp.Versioning rather than fail-fast at bootstrap) are both chosen to match vanilla Asp.Versioning semantics and documented/tested. Happy to switch to verb-scoped grouping if you'd prefer.

Testing & docs

• 66 tests: fail-fast config guards, per-role version bucketing, route grouping, idempotency, OperationId uniqueness, plus the native-vs-bridge parity and OpenAPI tiers.
• Wired into CI via CIHttpAspVersioning (net10-pinned, mirroring CIPolecat); package added to the Pack target.
• docs/guide/http/versioning.md gains an Asp.Versioning.Http Package Support section with a native-vs-bridge decision matrix and usage/OpenAPI guidance. Includes a 6.17 badge, which can be changed if needed.

[Copilot]

Pull request overview

Adds a new companion package that bridges Wolverine HTTP endpoint metadata into the Asp.Versioning.Http ecosystem (routing/matching, reporting, and ApiExplorer/OpenAPI behavior), while keeping Wolverine’s existing native URL-segment versioning intact.

Changes:

• Introduces WolverineFx.Http.AspVersioning (net10-only) with an IHttpPolicy that attaches ApiVersionSet / MapToApiVersion metadata at bootstrap.
• Updates Wolverine.Http internals to support setting RouteEndpointBuilder.ApplicationServices when required by endpoint finalizers, and generalizes version-resolution logic for reuse.
• Adds extensive new test coverage (hostless + parity/integration tiers), docs updates, and CI wiring for net10-pinned execution.

Reviewed changes

Copilot reviewed 34 out of 34 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
wolverine.slnx	Adds the new net10-only AspVersioning projects to the solution but excludes them from default build.
src/Http/Wolverine.Http/HttpChain.EndpointBuilder.cs	Adds RequiresApplicationServices and sets RouteEndpointBuilder.ApplicationServices accordingly during endpoint build.
src/Http/Wolverine.Http/HttpChain.cs	Updates operation-id documentation (used by versioning policies to disambiguate).
src/Http/Wolverine.Http/AssemblyAttributes.cs	Grants friend access to the new AspVersioning package and its tests.
src/Http/Wolverine.Http/ApiVersioning/ApiVersionResolver.cs	Generalizes deprecation detection to IApiVersionProvider.Options and exposes reusable resolution helper.
src/Http/Wolverine.Http.Tests/ApiVersioning/MultiVersionResolverTests.cs	Adds regression coverage for deprecation propagation through [MapToApiVersion].
src/Http/Wolverine.Http.AspVersioning/WolverineHttpOptionsExtensions.cs	Adds UseAspVersioning() entry point to register the integration policy idempotently.
src/Http/Wolverine.Http.AspVersioning/Wolverine.Http.AspVersioning.csproj	New net10-only package project referencing Asp.Versioning.Http.
src/Http/Wolverine.Http.AspVersioning/VersionedChain.cs	Encapsulates per-chain version buckets (supported/deprecated/advertised) and neutral status.
src/Http/Wolverine.Http.AspVersioning/AssemblyAttributes.cs	Exposes internals to the AspVersioning test project.
src/Http/Wolverine.Http.AspVersioning/AspVersioningPolicy.cs	Core bootstrap-time policy that groups chains by route and applies Asp.Versioning metadata.
src/Http/Wolverine.Http.AspVersioning/AdvertisedVersionResolver.cs	Resolves [AdvertiseApiVersions] across method+class to contribute to version sets.
src/Http/Wolverine.Http.AspVersioning.Tests/Wolverine.Http.AspVersioning.Tests.csproj	New net10-only test project and dependency set (Alba, Asp.Versioning, ApiExplorer, Swashbuckle).
src/Http/Wolverine.Http.AspVersioning.Tests/ValidationTests.cs	Validates fail-fast guards and UseAspVersioning() idempotency.
src/Http/Wolverine.Http.AspVersioning.Tests/Usings.cs	Adds global xUnit using for the test project.
src/Http/Wolverine.Http.AspVersioning.Tests/SetBuildingTests.cs	Tests version bucketing and ApiVersionSet construction rules.
src/Http/Wolverine.Http.AspVersioning.Tests/PolicyOutputTests.cs	Verifies attached metadata models, idempotency, tags behavior, and service-provider requirement.
src/Http/Wolverine.Http.AspVersioning.Tests/Parity/UrlSegmentParityTests.cs	Parity tests for URL-segment authoring (Asp.Versioning semantics, not route rewriting).
src/Http/Wolverine.Http.AspVersioning.Tests/Parity/ParityFixture.cs	Shared host bootstrap for parity tiers (Wolverine + Asp.Versioning wiring).
src/Http/Wolverine.Http.AspVersioning.Tests/Parity/ParityEndpoints.cs	Defines native minimal-API twins and Wolverine twins for parity verification.
src/Http/Wolverine.Http.AspVersioning.Tests/Parity/OpenApiParityTests.cs	OpenAPI/ApiExplorer parity assertions between native and Wolverine twins.
src/Http/Wolverine.Http.AspVersioning.Tests/Parity/NativeParityTests.cs	End-to-end routing/header/error parity assertions for multiple version readers.
src/Http/Wolverine.Http.AspVersioning.Tests/Parity/DedicatedHostParityTests.cs	Parity coverage for global Asp.Versioning options requiring dedicated hosts.
src/Http/Wolverine.Http.AspVersioning.Tests/Parity/AspVersioningIntegrationContext.cs	Shared Alba integration host + swagger/versioned-doc wiring and helpers.
src/Http/Wolverine.Http.AspVersioning.Tests/Parallelization.cs	Forces per-assembly xUnit collection behavior for test stability.
src/Http/Wolverine.Http.AspVersioning.Tests/HttpChainExtensions.cs	Helper extensions to materialize endpoints and inspect version/tag metadata.
src/Http/Wolverine.Http.AspVersioning.Tests/HostlessAspVersioningContext.cs	Hostless fixture building a minimal container able to satisfy Asp.Versioning finalizers.
src/Http/Wolverine.Http.AspVersioning.Tests/GroupingTests.cs	Tests route-based grouping normalization and the chosen verb-agnostic grouping semantics.
src/Http/Wolverine.Http.AspVersioning.Tests/AdvertisedVersionResolverTests.cs	Unit tests for [AdvertiseApiVersions] merge/deprecation behavior.
docs/guide/http/versioning.md	Documents the Asp.Versioning bridge, decision matrix, usage, and OpenAPI guidance.
Directory.Packages.props	Adds centralized versions for Asp.Versioning.Http and Asp.Versioning.Mvc.ApiExplorer.
build/CITargets.cs	Adds CIHttpAspVersioning target to run the net10-only test suite.
build/build.cs	Adds the new AspVersioning package project to the pack list.
.github/workflows/http.yml	Runs the new CIHttpAspVersioning target in the HTTP workflow (net10 SDK already set up).

---

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

[knotekbr]

Fixed