Overview
This repository packages one focused extension library for Asp.Versioning. It still centers REST-style version negotiation through Accept-header parameters, but it now also adds semantic API version types that can carry patch numbers, prerelease labels, and build metadata without leaving Asp.Versioning's ApiVersion model.
Because the repository contains a single package, the value is not package selection. It is one opinionated integration layer that keeps service registration, version formatting, controller metadata, ApiExplorer grouping, and version-error translation aligned when an API contract needs more than major/minor versions.
Concepts
The concepts in this repository revolve around treating versioning as one contract: the version reader, the semantic version shape, and the error path all need to agree on how a request is negotiated and how the chosen version appears in tooling.
RESTful registration and media-type filtering
Codebelt.Extensions.Asp.Versioning keeps Asp.Versioning registration, MVC conventions, and ApiExplorer setup in one place through AddRestfulApiVersioning and RestfulApiVersioningOptions. RestfulApiVersionReader narrows version negotiation to an explicit allow-list of Accept header media types, so APIs that version through representation metadata can reject unrelated media types instead of treating every header as a version source.
Semantic API versions that still fit ApiExplorer
The semantic-version additions are the main change in this repository's current shape. Codebelt.Extensions.Asp.Versioning now provides SemanticApiVersion, SemanticApiVersionParser, and SemanticApiVersionFormatter so controller conventions and runtime code can carry major.minor.patch versions plus prerelease and build metadata while still honoring the format tokens that Asp.Versioning and ApiExplorer already use. SemanticApiVersionAttribute, MapToSemanticApiVersionAttribute, and SemanticApiVersion.FromVersion with VersionConversionOptions extend that model into declarative controller metadata and four-part System.Version conversion.
Versioning failures translated into pipeline exceptions
When negotiation or problem-details output fails, the package keeps versioning on the same error path as the rest of an API. Codebelt.Extensions.Asp.Versioning can either preserve the built-in RFC 7807 writer or translate problem-details payloads into HttpStatusCodeException instances, and UseRestfulApiVersioning can convert bare status-code responses into exceptions that the rest of the pipeline can format consistently.
Usage guidance
Use this repository when your API contract needs Accept-header based version negotiation and you want semantic versions such as 1.2.3-beta+build.5 to flow through controller metadata, runtime formatting, and ApiExplorer output without custom plumbing.
If your API only needs the default major/minor Asp.Versioning model, or if versions are expressed through routes or query-string parameters instead of media types, configure Asp.Versioning directly and skip this package's opinionated registration and exception-translation layer.
