Versioning with WebAPI .Net Core does not work as expected

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?

Here's a great package which adds the versioning to swagger in a great way https://github.com/rh072005/SwashbuckleAspNetVersioningShim — Marcus Höglund, Oct 16 '18 at 18:25
Your answer did solve my issue. It was worthy of an answer. Would you mind converting it into an answer? — Lost, Oct 17 '18 at 01:03

score 5 · Answer 1 · answered Oct 25 '18 at 20:54

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.

score 1 · Accepted Answer · answered Oct 17 '18 at 06:17

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

Versioning with WebAPI .Net Core does not work as expected

2 Answers2