Using v1 pattern in url for minimal API .NET 6 versioning

[Sonic3R]

Hi

I want to use /v1/orders or /v2/orders pattern using api versioning

Well, I configured like:

var builder = WebApplication.CreateBuilder(args);
ApiVersion apiV1 = new ApiVersion(1);
ApiVersion apiV2 = new ApiVersion(2);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddApiVersioning(opts =>
{
    opts.ReportApiVersions = true;
    opts.ApiVersionReader = new UrlSegmentApiVersionReader();
}).AddApiExplorer(opts =>
{
    opts.GroupNameFormat = "'v'VVV";
    opts.SubstituteApiVersionInUrl = true;
});

builder.Services.AddTransient<IConfigureOptions<SwaggerGenOptions>, ConfigureSwaggerOptions>();
builder.Services.AddSwaggerGen();

// other DI calls

var app = builder.Build();
var orderApiSet = app.NewApiVersionSet("Orders").Build();

app.MapGet("/orders", async ([FromServices] IOrdersRepository orderRepo) =>
{
    return await orderRepo.ListAsync(...);
}).WithApiVersionSet(orderApiSet)
  .HasApiVersion(apiV1);

app.MapGet("/orders", async ([FromServices] IOrdersRepositoryV2 orderRepo) =>
{
    return await orderRepo.List1Async(...);
}).WithApiVersionSet(orderApiSet)
  .HasApiVersion(apiV2);


app.UseSwagger();
app.UseSwaggerUI(opts =>
{
        var descriptions = app.DescribeApiVersions();
        foreach (var desc in descriptions)
        {
            var url = $"/swagger/{desc.GroupName}/swagger.json";
            var name = desc.GroupName.ToUpperInvariant();
            opts.SwaggerEndpoint(url, $"Orders API {name}");
        }
});

await app.RunAsync();

I expected if type in url like /v1/orders that would go to first MapGet but I got 404 page. As well as for /v2/orders

If I type /orders without any vX then I got 400 that api version is not specified.

How to solve this ?

A solution would be app.MapGet("v{version:apiVersion}/orders") but in SwaggerUI displays like:

But is not quite good because I already selected api version from top right corner dropdown, don't see the purpose of {version} in call

[commonsensesoftware]

Thanks for reporting this. There are lot of possible setup variations and I hadn't tried this one. There is a bug in ASP.NET Core's implementation of the API Explorer for Minimal APIs that is causing this. I've reported it so we'll see what they say. API Versioning relies on the ApiParameterDescription being discovered and populated so that it can match it up for substitution. The parameter is not discovered so there is nothing to match.

In the meantime, there are a few possible workarounds. The best option at the moment would probably be to use a custom IOperationFilter in Swashbuckle and perform the substitution yourself. That will be predicated on using the same route parameter name in your templates (e.g. {version}, but you define it).

• The ApiDescription.GetApiVersion() extension method with get you the associated ApiVersion
• ApiVersion.ToString can then be called using ApiExplorerOptions.SubstitutionFormat to get the substitution value
• Replace {version} (or appropriate token) in ApiDescription.RelativePath

This effectively the same steps API Versioning uses. Without a match parameter though, there's no way to accurately know how to generate the {<name>} token for substitution.

[commonsensesoftware]

The ASP.NET Core team confirmed the bug, but they've yet to provide any feedback as to when the fix might be published. I'm getting the impression that it may not happen until .NET 7.0. It's a pretty glaring oversight IMHO and should be included in a service release. The bug affects more than just API Versioning.

Regardless, I've come up with a way to work around the problem and hide the internal yuckiness of it. It's a sticking point for me that the fix should not result in a change (e.g. breaking change) to API Versioning's public API surface. It's not the ideal solution, but I've got something working that will make this scenario work without exposing the bits that will likely go away in a future patch or version of ASP.NET Core.

Expect to see this fixed in the next release.

[commonsensesoftware]

@knightian is that a question? Looks like you are probably missing a using directive. The recommended statements are:

using Asp.Versioning;
using Asp.Versioning.Conventions;

[knightian]

@knightian is that a question? Looks like you are probably missing a using directive. The recommended statements are:

using Asp.Versioning;
using Asp.Versioning.Conventions;

Entire Asp.Versioning.Mvc.ApiExplorer was not even added to my project by nuget. Seems it needed to be manually added.

Didn't think I would be using Mvc stuff for minimal?

[commonsensesoftware]

Yeah, it's unfortunate, but the much of the implementation for the API Explorer (Microsoft.AspNetCore.Mvc.ApiExplorer) depends on Microsoft.AspNetCore.Mvc.Core. I'm not entirely sure why that is, but it's a decision that was made years ago and can't easily change. The core abstractions - Microsoft.AspNetCore.Mvc.Abstractions - is part of the MVC Core surface area, but doesn't have a dependency on the Microsoft.AspNetCore.Mvc.Core.

I considered attempting to split the two apart, but it wasn't buying much value. I did move the abstractions into Asp.Versioning.Http, which is the bare requirement for Minimal APIs. I also didn't want to repeat the mistakes of the ASP.NET team will reimplemented some API Explorer implementation and missed supported use cases. I purposely kept Mvc in the name so there is a way to break things a part in the future if it ever makes sense. For this particular use case, there really isn't any MVC being used. Since the ASP.NET Core model is a now a FrameworkReference as opposed to individual packages, it shouldn't be of any concern; however, I did try to keep things as isolated as possible.

There are arguably a few things under the MVC name that aren't really MVC. Term Web API is still used even though it's branded under MVC. If Swagger/OpenAPI would have been more mature - say 5+ years ago, I think you might have seen things unfold and be named differently. I hope that helps clear things up.