[thomasluizon]

Requests without api-version and with api-version: 1.0 keep the existing v1 contract. api-version: 2.0 selects the same handlers under v2, while unsupported versions return HTTP 400 with a clear Problem Details error. Existing routes and DTO shapes are preserved.

Closes thomasluizon/orbit-tickets#1416

The API project pins Asp.Versioning.Mvc and Asp.Versioning.Mvc.ApiExplorer to 10.2.1. All 31 controllers declare both versions. ServiceCollectionExtensions.Infrastructure.cs configures header selection, the implicit v1 default, supported-version reporting, and CORS permission for the new header. References to Orbit's HTTP helper are qualified where the dependency introduces a conflicting type name.

The existing Microsoft OpenAPI generator produces src/Orbit.Api/openapi.json for v1 and src/Orbit.Api/openapi_v2.json for v2. Both describe 203 operations and 158 schemas. Scalar lists both documents, the existing breaking-change gate continues comparing v1 at its original path, and .github/workflows/test.yml checks freshness of both snapshots. src/Orbit.Api/CLAUDE.md documents separate v2 DTOs/actions for breaking changes and v1 retirement through MinSupportedVersion after client adoption.

Test evidence

• dotnet build Orbit.slnx: exit 0, zero errors. Warnings include existing package/compiler warnings and versioning advice for the deliberately configured default and existing OpenAPI generator.
• dotnet test tests/Orbit.Infrastructure.Tests --filter 'FullyQualifiedName~ApiVersioningTests|FullyQualifiedName~SkipUndoContractTests': 14 passed. Tests invoke the real routing middleware directly without starting a server. They cover omitted/v1/v2 responses for habits, config, and profile; profile errors; v2 selection and v9 rejection for every controller route; malformed versions; header-only selection; production CORS policies; and document version isolation.
• dotnet test tests/Orbit.Domain.Tests --no-build: 666 passed, exit 0.
• dotnet test tests/Orbit.Application.Tests --no-build: 5,466 passed, exit 0.
• dotnet test tests/Orbit.Infrastructure.Tests --no-build: 3,355 passed, exit 0.
• dotnet test tests/Orbit.Analyzers.Tests --no-build: 32 passed, exit 0.
• oasdiff breaking origin/main:src/Orbit.Api/openapi.json src/Orbit.Api/openapi.json --fail-on ERR: exit 0, no breaking changes. Both committed snapshots match build output.
• The first full infrastructure run observed SkipUndoContractTests.GeneratedOpenApi_AppendsUndoAndOptionalSkipId_KeepingSkipNoContent fail because its unchanged assertion expected every parameter to be a path parameter. The updated assertion preserves the exact id/skipId path contract and separately verifies that api-version is an optional header. The focused rerun passed all 14 tests.

External interface evidence

• Live NuGet catalogs confirmed 10.2.1 for both packages: MVC versions and API Explorer versions. After restore, both installed .nuspec files identified source commit b4e6e0f41d3f9fcf7042dc364a45ecbc38b88e4f. The installed XML API descriptions and matching source confirmed versioning options, header reader, and API Explorer grouping. Re-derive by restoring the API project and inspecting those package files under the NuGet package cache.
• The error assertions use the actual library producer, rather than a mocked response: EndpointProblem sets code, title, and status. Routing tests observed HTTP 400 with code: UnsupportedApiVersion; successful controller requests reported api-supported-versions: 1.0, 2.0.
• Microsoft's installed API descriptions and OpenApiOptions source confirm that named documents filter descriptions by GroupName. The document generator confirms the special v1 filename and _v2 suffix; the build emitted both files at those exact paths.
• Scalar 2.18.0's installed XML descriptions and matching source confirm AddDocument(documentName, title, isDefault: ...). CORS tests evaluate the real ICorsService against production policies; their CorsResult properties were confirmed in the installed ASP.NET Core reference XML.

Assumptions

• Kept openapi.json as the v1 snapshot and added openapi_v2.json, rejecting a renamed v1 snapshot because that would change the existing compatibility gate's contract path.
• Used versioned MVC API Explorer with the existing Microsoft generator, rejecting Asp.Versioning.OpenApi: that package also added unrelated validation enum metadata and made the v1 comparison report five breaking parameter restrictions. The selected integration preserves the existing schemas and passes the v1 comparison.

[sonarqubecloud]

Quality Gate passed

Issues
7 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[pullfrog]

✅ No new issues found.

Reviewed changes Checked header-based version selection, existing-client compatibility, all controller declarations, generated contracts, and regression coverage.

• Version routing: All 31 controllers support v1 and v2 on existing routes, omitted headers default to v1, and unsupported versions return HTTP 400.
• HTTP compatibility: CORS permits the version header and exposes supported-version headers; existing mobile and web clients continue using implicit v1 without changes.
• API documents: Separate v1/v2 documents and Scalar entries preserve all 203 operations and 158 schemas. Structural comparison against the base confirmed no changes beyond document metadata and version-header parameters.
• Verification: All 14 focused routing/contract tests and the full 3,355-test infrastructure suite passed. Regenerating both OpenAPI documents left the worktree clean. Other test suites were not rerun.

  ^{｜ View workflow run ｜ Using gpt-6.1-sol ｜ 𝕏}