ASP.NET Core API version

Question

I'm trying to create API with ASP.NET Core and their version. I installed Microsoft.AspNetCore.Mvc.Versioning. What I like to have is all the API with the version in the URL, so it is easy to understand what version of the API I use. For example /api/v1/TableAzureCategory.

For thata, in my Startup.cs I added the following lines of code:

services.AddApiVersioning(config =>
{
    config.DefaultApiVersion = new ApiVersion(1, 0);
    config.AssumeDefaultVersionWhenUnspecified = true;
    config.ReportApiVersions = true;
    config.ApiVersionReader = new UrlSegmentApiVersionReader();
});

Then, in my API controller I added some decorations

[ApiController]
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/[controller]")]
public class TableAzureCategoryController : ControllerBase
{
}

I run the application, open Swagger and this is what I see (basically the {version:apiVersion} is not replaced with the API version)

I looked around but I found only implementation like mine above. Any ideas?

Answer 1

Another way of achieving this would be to create a query-based versioning solution.

Let's say we have two controllers: ExampleV1Controller and ExampleV2Controller

using Microsoft.AspNetCore.Mvc;

namespace MyAPI.Controllers
{
    [ApiController]  
    [ApiVersion("1.0")]  
    [Route("api/example")]
    public class ExampleV1Controller : ControllerBase  
    {
        [HttpGet]  
        public IActionResult Get()  
        {  
            return new OkObjectResult("Example API v1");  
        }
    }

    [ApiController]  
    [ApiVersion("2.0")]  
    [Route("api/example")]
    public class ExampleV2Controller : ControllerBase  
    {
        [HttpGet]  
        public IActionResult Get()  
        {  
            return new OkObjectResult("Example API v2");  
        }
    }
}

As by your Startup.cs configuration, it will default to API version 1.0. To make a request to the V2 version, use https://localhost:5001/api/example?api-version=2.0.

I did not test this myself, but it should work.

Answer 2

The {version} route parameter behaves just like any other route parameter. If the route was values/{id}/subvalues you would expect a parameter named id that must be filled in.

The API Explorer extensions for API Versioning know the version associated with an API. This value is used as the default value, but OpenAPI/Swagger generators (ex: Swashbuckle) may not use the default value without a little help (refer to the end-to-end Swagger Example). If, and only if, you are versioning by URL segment, you can have the API Explorer extensions expand the route template with the default value and remove the API version parameter using the configuration:

services.AddVersionedApiExplorer(options => options.SubstituteApiVersionInUrl = true);

In the example provided, the version route parameter will be removed and the route template will be updated to "api/v1.0/TableAzureCategory", which I presume is what you want.