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 Asp.Versioning v10 package and Microsoft's Microsoft.AspNetCore.OpenApi 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.

What is API versioning and why is it important in .NET 10?

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.

Which libraries are essential for API versioning and OpenAPI in .NET 10?

The two main libraries are Asp.Versioning (version 10) and Microsoft.AspNetCore.OpenApi. 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 /openapi/v1.json. These libraries together allow you to define versions, generate separate OpenAPI documents per version, and avoid duplicate code. Additionally, for visualization, you can use Swashbuckle.AspNetCore.SwaggerUI or Scalar.AspNetCore.

How do you implement API versioning with Minimal APIs in .NET 10?

With Minimal APIs, API versioning is achieved by using the Asp.Versioning library. First, install the package and configure versioning in Program.cs using builder.Services.AddApiVersioning(). 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 [ApiVersion("1.0")] or by using the WithApiVersionSet method. For example:

app.MapGet("/api/v{version:apiVersion}/items", () => ...)
   .WithApiVersionSet(versionSet);

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.

How do you integrate OpenAPI documentation with versioned APIs?

Integration is done by combining Microsoft.AspNetCore.OpenApi with the versioning setup. After configuring versioning, call builder.Services.AddOpenApi() and then use app.MapOpenApi(). 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 app.MapOpenApi("/openapi/{version}.json") 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.

How can you visualize versioned API documentation using SwaggerUI and Scalar?

After generating OpenAPI documents per version, you can visualize them using Swashbuckle.AspNetCore.SwaggerUI or Scalar.AspNetCore. Both tools allow you to display multiple versions in a dropdown or separate tabs. For SwaggerUI, install the package, then configure it in Program.cs to read the versioned OpenAPI documents. For example:

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/openapi/v1.json", "Version 1");
    c.SwaggerEndpoint("/openapi/v2.json", "Version 2");
});

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.

What are the key steps to combine API versioning with OpenAPI in .NET 10?

Follow these steps for a clean integration:

1. Set up API versioning using Asp.Versioning v10 in your service collection.
2. Define version sets and apply version attributes to your endpoints (controllers or Minimal APIs).
3. Add OpenAPI support via AddOpenApi() and configure multiple documents for each version.
4. Map the versioned OpenAPI endpoints using MapOpenApi with version placeholders.
5. Add a UI tool (SwaggerUI or Scalar) that references the versioned documents.
6. Test each version to ensure separate schemas and no duplication.

This approach minimizes custom code and leverages official packages, making maintenance easier as your API grows.