12. API versioning and OpenAPI

// Asp.Versioning.Http / Asp.Versioning.Mvc packages
builder.Services.AddApiVersioning(o =>
{
    o.DefaultApiVersion = new ApiVersion(1, 0);
    o.AssumeDefaultVersionWhenUnspecified = true;
    o.ReportApiVersions = true;                         // api-supported-versions header
    o.ApiVersionReader = new UrlSegmentApiVersionReader();
});

[ApiVersion("1.0")][ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/orders")]
public class OrdersController : ControllerBase { [HttpGet, MapToApiVersion("2.0")] public IActionResult GetV2() => Ok(); }

// OpenAPI (.NET 9+ built in)
builder.Services.AddOpenApi();
app.MapOpenApi();                                       // /openapi/v1.json
// UI: Scalar (app.MapScalarApiReference()) or Swashbuckle/NSwag Swagger UI