1. Just to clarify, the cases where excetions occurred in v5 are now returned as 4xx responses which is a big improvement, I wasn't saying that I was getting any exceptions in version 6.x so apologies for any confusion there.
2. We've followed your suggestion here: https://stackoverflow.com/questions/56738937/net-core-webapi-fall-back-api-version-in-case-of-missing-minor-version which we used to handle the status. I like the idea of adding both versions although there might be reservations about developers managing this properly, adding a new version when released might make mistakes more likely than updating the version constant and would also mean that it appears in redoc/swagger documentation as preview/obsolete/current so could be confusing. I'll have a play with adding middleware in the new year, thankyou for the suggestion and the effort in knocking up a poc.

workaround found: using similar middleware to above but using the IApiVersionDescriptionProvider to check if a requested -preview version is known. If not, but there's one that matches on all but status and has a null/empty status, we adjust the requested version to that.

@stevendarby , fundamentally API versions are discrete and immutable. If they're not, then things are unpredictable and nondeterministic. There's absolutely nothing wrong with continuing to support a -preview version; especially if it is exactly the same as the released version. What I can't quite understand is why you would want to get down into the bowels of routing and a custom MatcherPolicy for this (unless there are other reasons). Why not just map both versions to the same place?

[ApiVersion("2024-01-01")]
[ApiVersion("2024-01-01-preview")]
[Route("my/api")]
public class MyApiController : ControllerBase
{
}

This is a trivial example. You don't have to use attributes. You could use conventions. You could also use custom attributes that are more tailored to your needs; for example, [OurApiVersion("2024-01-01", IncludePreview = true)]. This would emit 2024-01-01 and 2024-01-01-preview.

Using the IApiVersionDescriptionProvider can work, but only you know if it's the right choice. The results are collated across all APIs and versions. If you're versioning scheme is symmetrical, then I would expect it to work. On the other hand, if it's asymmetrical, then it's possible that one API has both 2024-01-01 and 2024-01-01-preview, while another has only one of them. This is specific to your implementation.

Consideration should be given to other implications of changing what the client requested. I presume at point, you probably do shutdown the preview version for good (but maybe not). One way you'd gauge if that is safe to do is looking at telemetry of requested API versions. If you're manipulating the value, the behavior becomes brittle. Depending on when and where you record the value, it may be unexpected because some other part of the pipeline changed it (and you didn't notice or realize it).

I'm here to help you achieve your goals, but for this scenario, I recommend staying out of custom routing land.

Thanks @commonsensesoftware. I’m hesitant to add additional preview attributes because of the extra versions that’ll appear in swashbuckle/swagger and get reported in supported/deprecated version response headers. We want to allow continued use of “-preview” without advertising it as such, if that makes sense.

I think the workaround will work as our versioning is always symmetrical. We have up 3 sets of controllers in a given service (deprecated, stable, preview) which are reversioned and shifted along at fairly fixed intervals that are communicated to customers.

Already answered here https://stackoverflow.com/a/66788306

@stevendarby I had a suspicion you might say that. Controlling and filtering the reported metadata is vastly easier than changing routing. There are multiple approaches and things you can do, but under the assumption that you don't want to advertise any information about previews anywhere, including OpenAPI/Swagger, but you still want things to be routed, you only need to change a few things:

1. IReportApiVersions
2. IApiVersionDescriptionProvider
3. IApiVersionDescriptionProviderFactory (for completeness)
   a. This is required if you use DescribeApiVersions
   b. This covers the edge case with Minimal APIs, which are registered outside of DI
   c. If you use IApiVersionDescriptionProvider directly and without Minimal APIs, this is unnecessary
   d. I hope/plan to simplify this requirement in the future

IReportApiVersions

This will prevent any API version with a status from being reported by any API.

using Asp.Versioning;

internal sealed class NoPreviewApiVersionReporter : IReportApiVersions
{
    private readonly DefaultApiVersionReporter reporter;

    public NoPreviewApiVersionReporter( ISunsetPolicyManager sunsetPolicyManager ) =>
        reporter = new( sunsetPolicyManager );

    public ApiVersionMapping Mapping => reporter.Mapping;

    public void Report( HttpResponse response, ApiVersionModel apiVersionModel )
    {
        var filtered = new ApiVersionModel(
            WithoutPreviews( apiVersionModel.DeclaredApiVersions ),
            WithoutPreviews( apiVersionModel.SupportedApiVersions ),
            WithoutPreviews( apiVersionModel.DeprecatedApiVersions ),
            Enumerable.Empty<ApiVersion>(),
            Enumerable.Empty<ApiVersion>() );

        reporter.Report( response, filtered );
    }

    private static IEnumerable<ApiVersion> WithoutPreviews( IEnumerable<ApiVersion> apiVersions )
    {
        foreach ( var apiVersion in apiVersions )
        {
            if ( string.IsNullOrEmpty( apiVersion.Status ) )
            {
                yield return apiVersion;
            }
        }
    }
}

IApiVersionDescriptionProvider

This will remove the description for any API version with a status. This will prevent an OpenAPI document from being
created by Swashbuckle for those API versions.

using Asp.Versioning;
using Asp.Versioning.ApiExplorer;
using Microsoft.Extensions.Options;

internal sealed class NoPreviewApiDescriptionProvider : DefaultApiVersionDescriptionProvider
{
    public NoPreviewApiDescriptionProvider(
        IEnumerable<IApiVersionMetadataCollationProvider> providers,
        ISunsetPolicyManager sunsetPolicyManager,
        IOptions<ApiExplorerOptions> apiExplorerOptions )
        : base( providers, sunsetPolicyManager, apiExplorerOptions ) { }

    protected override IReadOnlyList<ApiVersionDescription> Describe( IReadOnlyList<ApiVersionMetadata> metadata )
    {
        var results = base.Describe( metadata );
        var filtered = new List<ApiVersionDescription>( capacity: results.Count );

        for ( var i = 0; i < results.Count; i++ )
        {
            var result = results[i];

            if ( string.IsNullOrEmpty( result.ApiVersion.Status ) )
            {
                filtered.Add( result );
            }
        }

        return filtered;
    }
}

IApiVersionDescriptionProviderFactory (Optional)

This is used to create an IApiVersionDescriptionProvider for DescribeApiVersions. Minimal APIs create an EndpointDataSource outside of DI and it cannot be evaluated early enough for Swashbuckle if this isn't in place. You really only need this for completeness. If you aren't using Minimal APIs, then using IApiVersionDescriptionProvider from DI directly (as in earlier library versions) will work without this.

using Asp.Versioning;
using Asp.Versioning.ApiExplorer;
using Microsoft.Extensions.Options;

internal sealed class NoPreviewApiVersionDescriptionProviderFactory : IApiVersionDescriptionProviderFactory
{
    private readonly ISunsetPolicyManager sunsetPolicyManager;
    private readonly IApiVersionMetadataCollationProvider[] providers;
    private readonly IOptions<ApiExplorerOptions> options;
    private readonly Func<IEnumerable<IApiVersionMetadataCollationProvider>,
                          ISunsetPolicyManager,
                          IOptions<ApiExplorerOptions>,
                          IApiVersionDescriptionProvider> activator;

    public NoPreviewApiVersionDescriptionProviderFactory(
        Func<IEnumerable<IApiVersionMetadataCollationProvider>,
             ISunsetPolicyManager,
             IOptions<ApiExplorerOptions>,
             IApiVersionDescriptionProvider> activator,
        ISunsetPolicyManager sunsetPolicyManager,
        IEnumerable<IApiVersionMetadataCollationProvider> providers,
        IOptions<ApiExplorerOptions> options )
    {
        this.activator = activator;
        this.sunsetPolicyManager = sunsetPolicyManager;
        this.providers = providers.ToArray();
        this.options = options;
    }

    public IApiVersionDescriptionProvider Create( EndpointDataSource endpointDataSource )
    {
        var collators = new List<IApiVersionMetadataCollationProvider>( capacity: providers.Length + 1 )
        {
            new EndpointApiVersionMetadataCollationProvider( endpointDataSource ),
        };

        collators.AddRange( providers );

        return activator( collators, sunsetPolicyManager, options );
   

Setup

Now you just need to replace these services in your setup.

builder.Services.AddSingleton<IReportApiVersions, NoPreviewApiVersionReporter>();
builder.Services.AddSingleton<IApiVersionDescriptionProvider, NoPreviewApiDescriptionProvider>();
builder.Services.AddTransient<IApiVersionDescriptionProviderFactory>(
    static provider =>
        new NoPreviewApiVersionDescriptionProviderFactory(
            static ( p, m, o ) => new NoPreviewApiDescriptionProvider( p, m, o ),
            provider.GetRequiredService<ISunsetPolicyManager>(),
            provider.GetServices<IApiVersionMetadataCollationProvider>(),
            provider.GetRequiredService<IOptions<ApiExplorerOptions>>() ) );

Conclusion

I verified this setup against the OpenApiExample and it works as expected. Make additional changes as you see fit. It's not zero work, but this is much simpler and easy to understand than mucking around with routing IMHO.