Mastering API Versioning and OpenAPI in .NET 10: A Step-by-Step Guide

<p>API versioning is a critical practice for maintaining backward compatibility as your API evolves. In .NET 10, combining versioning with OpenAPI documentation has become cleaner thanks to the new <strong>Asp.Versioning v10</strong> package and Microsoft's <strong>Microsoft.AspNetCore.OpenApi</strong> library. This guide walks you through a step-based approach—from setting up versioning without OpenAPI to integrating documentation and visualizing it with SwaggerUI and Scalar. Whether you use controllers or Minimal APIs, you'll learn how to keep your API flexible and well-documented.</p> <h2 id="q1">What is API versioning and why is it important in .NET 10?</h2> <p>API versioning allows your API to introduce new features, fix bugs, or change behavior without breaking existing clients. In .NET 10, as with earlier versions, you can version via URL path, query parameters, or headers. The importance lies in maintaining backward compatibility—a critical aspect for production APIs. With .NET 10's enhanced built-in request validation and the maturity of Minimal APIs, versioning ensures that clients relying on an older version continue to work seamlessly while newer clients can adopt improvements. Proper versioning also helps in documenting and testing each version independently, reducing confusion and deployment risks.</p><figure style="margin:20px 0"><img src="https://devblogs.microsoft.com/dotnet/wp-content/uploads/sites/10/2026/04/api-versioning.webp" alt="Mastering API Versioning and OpenAPI in .NET 10: A Step-by-Step Guide" style="width:100%;height:auto;border-radius:8px" loading="lazy"><figcaption style="font-size:12px;color:#666;margin-top:5px">Source: devblogs.microsoft.com</figcaption></figure> <h2 id="q2">Which libraries are essential for API versioning and OpenAPI in .NET 10?</h2> <p>The two main libraries are <strong>Asp.Versioning</strong> (version 10) and <strong>Microsoft.AspNetCore.OpenApi</strong>. Asp.Versioning v10 is the first version to officially support both .NET 10 and the new built-in OpenAPI support, making integration straightforward. Microsoft.AspNetCore.OpenApi is Microsoft's own OpenAPI library for ASP.NET Core, which by default sets up the endpoint at <code>/openapi/v1.json</code>. These libraries together allow you to define versions, generate separate OpenAPI documents per version, and avoid duplicate code. Additionally, for visualization, you can use <strong>Swashbuckle.AspNetCore.SwaggerUI</strong> or <strong>Scalar.AspNetCore</strong>.</p> <h2 id="q3">How do you implement API versioning with Minimal APIs in .NET 10?</h2> <p>With Minimal APIs, API versioning is achieved by using the <strong>Asp.Versioning</strong> library. First, install the package and configure versioning in <code>Program.cs</code> using <code>builder.Services.AddApiVersioning()</code>. You can specify the default version, assume default version when unspecified, and choose the version reader (e.g., URL path or query string). Then, define your endpoints and apply versioning via attributes like <code>[ApiVersion("1.0")]</code> or by using the <code>WithApiVersionSet</code> method. For example:</p> <pre><code>app.MapGet("/api/v{version:apiVersion}/items", () => ...) .WithApiVersionSet(versionSet);</code></pre> <p>This allows each endpoint to be mapped to a specific version. You can also group endpoints by version sets, making it easy to manage multiple versions without cluttering your code.</p> <h2 id="q4">How do you integrate OpenAPI documentation with versioned APIs?</h2> <p>Integration is done by combining <strong>Microsoft.AspNetCore.OpenApi</strong> with the versioning setup. After configuring versioning, call <code>builder.Services.AddOpenApi()</code> and then use <code>app.MapOpenApi()</code>. The key is to generate separate OpenAPI documents for each version. You can achieve this by registering multiple OpenAPI documents based on API version groups. For instance, use <code>app.MapOpenApi("/openapi/{version}.json")</code> and define the document name per version. The Asp.Versioning v10 package simplifies this by automatically mapping versions to document names. This ensures that each version of your API has its own accurate OpenAPI schema, avoiding overlaps and errors.</p><figure style="margin:20px 0"><img src="https://uhf.microsoft.com/images/microsoft/RE1Mu3b.png" alt="Mastering API Versioning and OpenAPI in .NET 10: A Step-by-Step Guide" style="width:100%;height:auto;border-radius:8px" loading="lazy"><figcaption style="font-size:12px;color:#666;margin-top:5px">Source: devblogs.microsoft.com</figcaption></figure> <h2 id="q5">How can you visualize versioned API documentation using SwaggerUI and Scalar?</h2> <p>After generating OpenAPI documents per version, you can visualize them using <strong>Swashbuckle.AspNetCore.SwaggerUI</strong> or <strong>Scalar.AspNetCore</strong>. Both tools allow you to display multiple versions in a dropdown or separate tabs. For SwaggerUI, install the package, then configure it in <code>Program.cs</code> to read the versioned OpenAPI documents. For example:</p> <pre><code>app.UseSwaggerUI(c => { c.SwaggerEndpoint("/openapi/v1.json", "Version 1"); c.SwaggerEndpoint("/openapi/v2.json", "Version 2"); });</code></pre> <p>Scalar works similarly but offers a modern, clean interface. Both tools let developers test endpoints directly. By linking your versioned APIs to these UI tools, you provide an interactive, version-aware documentation experience for your consumers.</p> <h2 id="q6">What are the key steps to combine API versioning with OpenAPI in .NET 10?</h2> <p>Follow these steps for a clean integration:</p> <ol> <li><strong>Set up API versioning</strong> using Asp.Versioning v10 in your service collection.</li> <li><strong>Define version sets</strong> and apply version attributes to your endpoints (controllers or Minimal APIs).</li> <li><strong>Add OpenAPI support</strong> via <code>AddOpenApi()</code> and configure multiple documents for each version.</li> <li><strong>Map the versioned OpenAPI endpoints</strong> using <code>MapOpenApi</code> with version placeholders.</li> <li><strong>Add a UI tool</strong> (SwaggerUI or Scalar) that references the versioned documents.</li> <li><strong>Test each version</strong> to ensure separate schemas and no duplication.</li> </ol> <p>This approach minimizes custom code and leverages official packages, making maintenance easier as your API grows.</p>