.NET Swagger API Versioning

In this article, we'll walk through the steps on how to add versioning to your API and display different versions on your Swagger page in a C# .NET application.

C# .NET API Versioning with Swagger

Imagine you have an API with two versions: 1.0 and 2.0. The goal is to display these versions in Swagger’s UI so that developers can easily interact with the appropriate version of your API.

Install Required NuGet Packages

First, you need to install the following NuGet packages to enable API versioning and Swagger integration:

• Microsoft.AspNetCore.Mvc.Versioning
• Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer
• Swashbuckle.AspNetCore
• Swashbuckle.Core

These packages allow for API version management and Swagger generation.

Decorate Your Controllers

In order for Swagger to discover your API versions, you need to decorate your controllers with the appropriate attributes.

[ApiController]
[ApiVersion("1.0")]
[ApiExplorerSettings(GroupName = "v1")]
[Route("api/public/v{version:apiVersion}/[controller]")]
public class MyV1Controller : Controller
{
    // Controller logic for version 1.0
}

[ApiController]
[ApiVersion("2.0")]
[ApiExplorerSettings(GroupName = "v2")]
[Route("api/public/v{version:apiVersion}/[controller]")]
public class MyV2Controller : Controller
{
    // Controller logic for version 2.0
}

In this example:

• [ApiVersion]: Specifies the version of the API. It's important to be consistent with the version format (e.g., "1.0" vs "1").
• [ApiExplorerSettings]: Specifies the version group for Swagger to display. Ensure the group name matches the version you define in the controller (e.g., “V1” or “V2”).

Configure API Versioning in Program.cs

Now, configure API versioning in the Program.cs file to link the controllers to their respective versions.

builder.Services.AddApiVersioning(options =>
{
    options.ReportApiVersions = true;
    options.Conventions.Controller<MyV1Controller>().HasApiVersion(new Microsoft.AspNetCore.Mvc.ApiVersion(1, 0));
    options.Conventions.Controller<MyV2Controller>().HasApiVersion(new Microsoft.AspNetCore.Mvc.ApiVersion(2, 0));
});

In this step, you associate the controllers with their respective API versions (e.g., version 1.0 for MyV1Controller and version 2.0 for MyV2Controller).

Add Swagger Documentation for Each API Version

Next, add Swagger documentation for each version of your API. In Program.cs, configure Swagger to generate separate documentation for versions 1.0 and 2.0:

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo() { Title = "API v1", Version = "v1.0" });
    options.SwaggerDoc("v2", new OpenApiInfo() { Title = "API v2", Version = "v2.0" });
    options.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());
    options.CustomSchemaIds(x => x.FullName);
});

Here, we define two Swagger documents (V1 and V2) with corresponding titles and versions.

Set Up Swagger UI for Multiple Versions

Finally, configure the Swagger UI to display both API versions. In Program.cs, set up the Swagger UI to point to both versioned API endpoints:

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/swagger/v1/swagger.json", "API v1.0");
        options.SwaggerEndpoint("/swagger/v2/swagger.json", "API v2.0");
    });
}

In this step, Swagger UI is configured to show both versions of the API, making it easy for developers to test and interact with the respective versions.

By following these steps, you can effectively version your APIs in a C# .NET application and expose those versions via Swagger UI. This not only helps with version management but also provides clear documentation to your API consumers.