Versioning with WebAPI .Net Core does not work as expected - asp.net-core

Question

I am trying to introduce URL versioning into my .Net Core WebAPI application. I am also using Swagger web tools for ease of use for users.
Now, while trying to introduce versioning into my application, I referenced the docs here: https://github.com/Microsoft/aspnet-api-versioning/wiki/New-Services-Quick-Start#aspnet-core
Now, I made following code changes into my code:
Startup.cs/ConfigureServices I added code below:
services.AddApiVersioning(options => {
options.AssumeDefaultVersionWhenUnspecified = true;
});
Now, my controller annotations before any kind of versioning was added, looked like below:
[Produces("application/json")]
[Route("api/controllerName")]
and produces a URL which looks like something below:
http://localhost:12003/swagger/#!/Workspace/GetAll
Now, I added annotations below to enable api versioning:
. [ApiVersion("1.0")]
[Produces("application/json")]
[Route("api/v{version:apiVersion}/workspace")]
and now when I click on the same method listed in my swagger UI
the url looks like below:
http://localhost:12003/swagger/#!/controllername/ApiV_versionGetAll
While what I was expecting was something like:
http://localhost:12003/swagger/#!/controllername/V1.0/GetAll
Also on my swagger it is now asking me explicitly about entering version number. So I think my question boils down to two major points:
How I can I fix my URL? and what am I doing wrong?
Why is swagger now asking me to enter version number in API UI when I have explicitly stated that the version is going to be 1.0 in the annotation of the controller?

Answer 1

What you are missing is the complementary package for API versioning that supports an API version-aware API Explorer:
https://www.nuget.org/packages/Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer
Install-Package Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer
The API Explorer is how Swagger generators like Swashbuckle do all their work. The source and links are also available in the API versioning repo.
To achieve the result you want, you need to configure API version substitution in the URL:
services.AddMvcCore().AddVersionedApiExplorer( options => options.SubstituteApiVersionInUrl = true );
Note: that the call the AddMvcCore() is no longer required in API Versioning 3.0+
Documentation and samples are available in the official API versioning repo. I recommend reviewing the API Documentation wiki topic:
https://github.com/Microsoft/aspnet-api-versioning/wiki/API-Documentation
The accepted answer extends this package, which is fine as long as it stay up-to-date with the flavor of API versioning you are using. API Versioning always ships compatible API Explorer extensions on every release.

Answer 2

Setting up api versioning with swagger is indeed a tricky thing as it is lot's of pieces that need to be setup correctly.
Luckily for us, there's a great nuget packages called SwashbuckleAspNetVersioningShim which solves this in an excellent way.
Add it
Install-Package SwashbuckleAspNetVersioningShim -Version 2.2.1
Then follow the readme here