Api Versioning in .Net Core

Mastering API Versioning and Dynamic Swagger Implementation in .NET Core

As applications grow, APIs evolve frequently. Maintaining backward compatibility while introducing new features can be challenging. API versioning ensures old clients continue working, while Swagger (OpenAPI) provides interactive documentation for developers. In this post, we’ll dive deeper into dynamically generating Swagger JSON for multiple API versions in .NET Core.

Why Dynamic Swagger JSON?

When you have multiple API versions, it’s tedious to manually maintain separate Swagger documents for each version. Dynamic generation allows your Swagger UI to automatically pick up new versions as they are added to controllers, without extra configuration.

---

Setting Up API Versioning

// Program.cs
builder.Services.AddApiVersioning(options =>
{
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.ReportApiVersions = true;
});

builder.Services.AddVersionedApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV"; // e.g. v1, v2
    options.SubstituteApiVersionInUrl = true;
});

The AddVersionedApiExplorer service helps dynamically generate Swagger documents per API version.

---

Dynamically Adding Swagger JSON for All Versions

// Add Swagger generator
builder.Services.AddSwaggerGen(options =>
{
    var provider = builder.Services.BuildServiceProvider()
                   .GetRequiredService();

    foreach (var description in provider.ApiVersionDescriptions)
    {
        options.SwaggerDoc(description.GroupName,
            new Microsoft.OpenApi.Models.OpenApiInfo
            {
                Title = $"My API {description.ApiVersion}",
                Version = description.ApiVersion.ToString(),
                Description = "An example API with dynamic Swagger JSON"
            });
    }

    // Optional: Include XML comments for detailed docs
    var xmlFile = $"{System.Reflection.Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    options.IncludeXmlComments(xmlPath);
});

Here, we loop through all API versions exposed by IApiVersionDescriptionProvider and generate a separate Swagger JSON for each version automatically.

---

Configure Swagger UI for Multiple Versions

app.UseSwagger();
app.UseSwaggerUI(c =>
{
    var provider = app.Services.GetRequiredService<IApiVersionDescriptionProvider>();

    foreach (var description in provider.ApiVersionDescriptions)
    {
        c.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json",
                          $"API {description.GroupName.ToUpperInvariant()}");
    }

    c.RoutePrefix = string.Empty; // Swagger at root URL
});

Now, the Swagger UI will automatically display all versions, allowing developers to select v1, v2, v3, etc., without manually updating configuration when new versions are added.

---

Best Practices for Versioning with Swagger

• Use URL-based versioning for clarity: /api/v1/products
• Always document deprecated endpoints in Swagger with clear warnings.
• Use XML comments and IncludeXmlComments for richer API descriptions.
• Group APIs by version using IApiVersionDescriptionProvider to keep Swagger UI organized.
• Keep a consistent naming format: e.g., v1, v2, v3.

---

Conclusion

Dynamic Swagger JSON generation combined with API versioning ensures your APIs are:

• Scalable: Easily add new versions without reconfiguring Swagger manually.
• Maintainable: Clear documentation reduces support and onboarding issues.
• Developer-friendly: Interactive UI allows quick testing and understanding of endpoints.

Whether you are using .NET Core, Python FastAPI, or Node.js Express, dynamic API documentation is a must-have for modern development.

Pro Tip: Automate versioning and Swagger generation as part of your CI/CD pipeline to always keep documentation up-to-date with deployed APIs.