Configure Versioning in a .NET 8 Web Api

ebeeraheem

View Profile
20 views
Jun 21, 2025

Install the Microsoft.AspNetCore.Mvc.Versioning NuGet package

In your Program.cs file, configure API versioning by adding and configuring the necessary services

// Configure API version
builder.Services.AddApiVersioning(options =>
{
   options.DefaultApiVersion = new ApiVersion(1, 0);
   options.AssumeDefaultVersionWhenUnspecified = true;
   options.ReportApiVersions = true;
   options.ApiVersionReader = ApiVersionReader.Combine(
       new UrlSegmentApiVersionReader(),
       new HeaderApiVersionReader("X-Api-Version"));
}).AddApiExplorer(options =>
{
   options.GroupNameFormat = "'v'V";
   options.SubstituteApiVersionInUrl = true;
});

For example, the version one controller could be…

[ApiController]
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/[controller]")]
public class ProductsController : ControllerBase
{
   [HttpGet]
   public IActionResult Get()
   {
       return Ok("This is version 1.0");
   }
}

And the version two controller could be…

[ApiController]
[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/[controller]")]
public class ProductsV2Controller : ControllerBase
{
   [HttpGet]
   public IActionResult Get()
   {
       return Ok("This is version 2.0");
   }
}

I think you can further specify whether a version will be deprecated, or it has already been deprecated so that users can move to newer versions.

To get Swagger support, add the following to your SwaggerGen

builder.Services.AddSwaggerGen(c =>
{
   c.SwaggerDoc("v1", new OpenApiInfo { Title = "Your API", Version = "v1" });
   c.SwaggerDoc("v2", new OpenApiInfo { Title = "Your API", Version = "v2" });
   c.SwaggerDoc("v3", new OpenApiInfo { Title = "Your API", Version = "v3" });
   // Configure other Swagger options if needed
});