V10.2.0/support api alias

[gimlichael]

This pull request introduces support for API version aliasing using semantic version formats, making it easier for clients to specify API versions with shortened or compatibility-oriented tokens (like 1, 1.0, or 1.0.0). It adds a new parser for handling these aliases, updates the service registration to use the parser, and includes comprehensive functional tests to ensure compatibility. Documentation and solution files are also updated accordingly.

API Version Alias Support:

• Added a new ApiVersionAliasParser class that resolves friendly API version aliases (e.g., 1, 1.0, 1.0.0) to canonical ApiVersion instances, with fallback to the default parser. This enables flexible version token handling in APIs.
• Updated AddRestfulApiVersioning to automatically register the alias parser when a semantic default version is used, and introduced a new AddApiVersionParser extension method for custom parser registration.

Testing:

• Added a new test project Codebelt.Extensions.Asp.Versioning.FunctionalTests to the solution. [1] [2]
• Implemented SemanticApiVersionCompatibilityTest and SemanticApiVersionDefaultCompatibilityTest to verify that API endpoints correctly route requests using various semantic version formats and aliases. [1] [2]

Documentation and Solution Updates:

• Updated .docfx/toc.yml and .docfx/docfx.json to reflect new documentation structure and ensure correct file references. [1] [2]

[codecov]

Codecov Report

❌ Patch coverage is 98.75000% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 99.45%. Comparing base (cf312b0) to head (2ad8a03).

Files with missing lines	Patch %	Lines
...Extensions.Asp.Versioning/ApiVersionAliasParser.cs	97.05%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #34      +/-   ##
==========================================
- Coverage   99.60%   99.45%   -0.16%     
==========================================
  Files          10       11       +1     
  Lines         510      553      +43     
  Branches       82       86       +4     
==========================================
+ Hits          508      550      +42     
- Misses          2        3       +1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[greptile-apps]

Greptile Summary

This PR introduces ApiVersionAliasParser, which maps short semantic tokens like 1, 1.0, or 1.0.0 to canonical ApiVersion instances, and updates AddRestfulApiVersioning to auto-register this parser when the default API version is a SemanticApiVersion. A new AddApiVersionParser<T> extension method is also added for explicit parser registration, accompanied by a new functional test project.

• ApiVersionAliasParser (new): Resolves alias tokens before delegating to a configurable fallback parser; factory methods CreateSemanticVersionAlias generate major / major.minor / major.minor.patch aliases for one or more SemanticApiVersion instances.
• ServiceCollectionExtensions (updated): Auto-registers an alias parser for the default SemanticApiVersion inside AddRestfulApiVersioning, and exposes AddApiVersionParser<T> for registering custom parsers.
• Functional tests (new): Four test classes covering alias routing, production and non-production semantic versions, and a compatibility baseline with plain ApiVersion endpoints.

Confidence Score: 5/5

Safe to merge; core alias-parsing logic is correct and well-validated. The two findings are design observations about DI registration ordering that do not break anything under the standard .NET single-type resolution path.

The new ApiVersionAliasParser class is straightforward and handles null/empty alias maps with existing Validator guards. The auto-registration logic in AddRestfulApiVersioning is correct for the default case. The only concerns are that AddSingleton in AddApiVersionParser appends rather than replaces when following the documented multi-version pattern, and that SemanticApiVersionDefaultCompatibilityTest ends up overriding the auto-registered parser rather than exercising it. Neither breaks functionality under default DI resolution semantics.

ServiceCollectionExtensions.cs — the interaction between the auto-registration inside AddRestfulApiVersioning and a subsequent AddApiVersionParser call deserves a second look for the double-descriptor concern.

Important Files Changed

Filename	Overview
src/Codebelt.Extensions.Asp.Versioning/ApiVersionAliasParser.cs	New parser class mapping short semantic aliases to canonical ApiVersion instances; well-structured with appropriate validation and virtual TryParse for extensibility.
src/Codebelt.Extensions.Asp.Versioning/ServiceCollectionExtensions.cs	Adds auto-registration of alias parser for SemanticApiVersion defaults and new AddApiVersionParser extension; double-registration concern when auto-registration and explicit AddApiVersionParser are both used.
test/Codebelt.Extensions.Asp.Versioning.FunctionalTests/Codebelt.Extensions.Asp.Versioning.FunctionalTests.csproj	New test project; TargetFrameworks, test runner, and package references are all inherited from Directory.Build.props via the EndsWith('Tests') condition.
test/Codebelt.Extensions.Asp.Versioning.FunctionalTests/SemanticApiVersionCompatibilityTest.cs	Functional test verifying plain-ApiVersion aliases using a manually-built alias map; DefaultVersion is ApiVersion (not SemanticApiVersion) so auto-registration does not trigger here.
test/Codebelt.Extensions.Asp.Versioning.FunctionalTests/SemanticApiVersionDefaultCompatibilityTest.cs	Tests auto-registration + explicit AddApiVersionParser; auto-registers partial aliases for DefaultVersion then explicitly overrides with full alias map, leaving two IApiVersionParser registrations in DI.
test/Codebelt.Extensions.Asp.Versioning.FunctionalTests/SemanticApiVersionNonProductionTest.cs	Tests full semantic version strings (pre-release + build metadata) with SemanticApiVersionParser.Default; correctly overrides auto-registered alias parser.
test/Codebelt.Extensions.Asp.Versioning.FunctionalTests/SemanticApiVersionProductionTest.cs	Tests production-style semantic version routing with SemanticApiVersionParser.Default; mirrors NonProductionTest structure for release semantic versions.
test/Codebelt.Extensions.Asp.Versioning.Tests/SemanticApiVersionTest.cs	Adds two equality tests confirming SemanticApiVersion and ApiVersion are not equal even when major/minor match; important for alias parser correctness.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Client
    participant Reader as RestfulApiVersionReader
    participant Alias as ApiVersionAliasParser
    participant Fallback as DefaultParser
    participant Router as AspVersioningRouter

    Client->>Reader: "v=1 in Accept header"
    Reader->>Alias: TryParse 1
    alt alias match
        Alias-->>Reader: SemanticApiVersion 1.0.0
    else no alias found
        Alias->>Fallback: TryParse 1
        Fallback-->>Alias: ApiVersion 1.0
        Alias-->>Reader: ApiVersion 1.0
    end
    Reader->>Router: resolved ApiVersion
    Router-->>Client: 204 No Content

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant Client
    participant Reader as RestfulApiVersionReader
    participant Alias as ApiVersionAliasParser
    participant Fallback as DefaultParser
    participant Router as AspVersioningRouter

    Client->>Reader: "v=1 in Accept header"
    Reader->>Alias: TryParse 1
    alt alias match
        Alias-->>Reader: SemanticApiVersion 1.0.0
    else no alias found
        Alias->>Fallback: TryParse 1
        Fallback-->>Alias: ApiVersion 1.0
        Alias-->>Reader: ApiVersion 1.0
    end
    Reader->>Router: resolved ApiVersion
    Router-->>Client: 204 No Content

Loading

_{Reviews (2): Last reviewed commit: "🐛 fix and clarify semantic version alia..." | Re-trigger Greptile}