How to force v1.0 rather than render and accept v1

[The-Futurist]

I borrowed a project from the sample for my own project and its working fine, I'm grateful for the sample projects, they are a great help.

But something I noticed (and the sample behaves the same way) is that swagger generates a UI that shows v1 rather than v1.0 but shows v1.1 fine. The service also accepts a v1 or a v1.0.

I want to enforce the full version number though, I want Swagger to not render v1.0 as v1 and I want the service to reject a segment of v1 and only accept the full v1.0. Swagger does this in both the dropdown version list and in the rendered URL:

So what would need to change in this project to get that behavior? where a v1.0 always appears as v1.0 and not v1 ?

https://github.com/dotnet/aspnet-api-versioning/tree/main/examples/AspNetCore/WebApi/OpenApiExample

[commonsensesoftware]

This is covered by the Custom API Version Format Strings topic. From the example, you have set GroupNameFormat to be "'v'VVV" here:

aspnet-api-versioning/examples/AspNetCore/WebApi/OpenApiExample/Program.cs

Line 33 in 39cfc87

options.GroupNameFormat = "'v'VVV";

The minor version is optionally when 0. If you want to always show the 0, then change the configuration to:

options.GroupNameFormat = "'v'VV";

The v character is not part of the version, which why you need to include the literal 'v' if that's how you want it to render. Also keep in mind that formatting honors the original input so that the value roundtrips in a predictable way. This means you want to make sure that you used [ApiVersion(1.0)] (numeric way) or [ApiVersion("1.0")]. If you use [ApiVersion("1")] the minor version still does not show under all cases.

[The-Futurist]

Many thanks, that was an easy tweak. It certainly addresses the dropdown:

But the rendered URL here still comes up as simply v1

and when I access the endpoint each of these works:

https://localhost:7276/api/v1/DoctoralRecord/TestSupport

https://localhost:7276/api/v1.0/DoctoralRecord/TestSupport

I'd like to reject the v1 and only accept v1.0 forcing consumers to always specify a full version number.

Al version values in my app are numeric with trailing digits too.

Thanks for the link, I'll take a good look, that might get me to a solution.

[commonsensesoftware]

You can't cause 1 to be rejected, but 1.0 to be accepted out of the box. It might be possible through some configuration, but - honestly - it will probably be more trouble than it's worth. You can, however, have the URLs use v1.0 over v1. This is almost the same configuration as before a la:

options.SubstitutionFormat = "VV"; // the default is "VVV"

Note that this format configuration does not use include the 'v' literal in the format. That's because you would have already included it in your route template; for example, [Route("api/v{version:apiVersion}/[controller]")]. This setting configures how the API version is formatted when it is substituted in the template, which is already enabled via options.SubstituteApiVersionInUrl = true.

[The-Futurist]

Thank you, that's very very helpful, the Swagger UI now looks like I want it to:

Blocking the v1 case isn't a huge deal and I suppose I could write some simple interceptor that inspects the url and checks the format and rejects it if I really want to block it.

Many thanks.