Asp.Versioning 10.0 finalmente se entende com o OpenAPI nativo do .NET 10

Quando o ASP.NET Core 9 trocou o Swashbuckle pelo gerador nativo Microsoft.AspNetCore.OpenApi, faltou uma peça de cola: não existia uma forma limpa de ligar o novo pipeline ao Asp.Versioning e emitir um documento separado por versão. A correção chegou na semana passada. O post de 23 de abril no .NET Blog de Sander ten Brinke é o passo a passo oficial de “faça assim”, e ele anda de mãos dadas com os primeiros pacotes Asp.Versioning que têm como alvo o .NET 10.

Os pacotes que mudaram

Para minimal APIs, agora você referencia três pacotes, todos atuais em abril de 2026:

• Asp.Versioning.Http 10.0.0
• Asp.Versioning.Mvc.ApiExplorer 10.0.0
• Asp.Versioning.OpenApi 10.0.0-rc.1

Para controllers, troque Asp.Versioning.Http por Asp.Versioning.Mvc 10.0.0. O pacote OpenApi é quem faz o trabalho de verdade: ele liga o modelo do API explorer que a biblioteca de versionamento já produz ao pipeline de transformadores de documento que o Microsoft.AspNetCore.OpenApi espera. Antes desse release, você precisava escrever à mão um transformador que lesse IApiVersionDescriptionProvider e filtrasse operações por documento. Esse código agora vem de fábrica.

Um documento por versão, em três linhas

O registro de serviços não muda em relação ao versionamento pré-OpenAPI, com uma chamada extra a .AddOpenApi():

builder.Services.AddApiVersioning()
    .AddApiExplorer(options =>
    {
        options.GroupNameFormat = "'v'VVV";
    })
    .AddOpenApi();

O lado dos endpoint é onde a nova extensão aparece:

app.MapOpenApi().WithDocumentPerVersion();

WithDocumentPerVersion() enumera o que DescribeApiVersions() retornar e registra um documento por versão. Você acessa /openapi/v1.json e /openapi/v2.json e obtém exatamente as operações que pertencem a cada versão, sem IDs de operação compartilhados nem schemas duplicados vazando entre documentos. Tanto o Scalar (app.MapScalarApiReference()) quanto o Swagger UI (app.UseSwaggerUI()) descobrem os documentos automaticamente pelo mesmo provider de descrições de versão da API, então o seletor no navegador já vem ligado de graça.

Grupos de rotas versionados

Para minimal APIs, o lado das rotas continua compacto. Você declara uma API versionada uma vez e pendura grupos por versão nela:

var usersApi = app.NewVersionedApi("Users");

var usersV1 = usersApi.MapGroup("api/users").HasApiVersion("1.0");
var usersV2 = usersApi.MapGroup("api/users").HasApiVersion("2.0");

usersV1.MapGet("", () => Results.Ok(new { shape = "v1" }));
usersV2.MapGet("", () => Results.Ok(new { shape = "v2" }));

O nome Users vira o grupo da API; HasApiVersion é o que o API explorer lê para decidir a qual documento OpenAPI cada endpoint pertence.

Por que isso importa agora

Se você começou um app novo em ASP.NET Core 9 ou 10 e descartou o Swashbuckle por princípio, o versionamento era a única coisa que te puxava de volta. Com o Asp.Versioning.OpenApi 10.0.0-rc.1 essa saída de emergência se fecha. O sufixo RC é a única razão para esperar: a superfície da API é a que vai sair, e o time mira o GA junto com o trem de serviço do .NET 10. O exemplo completo vive no repositório do Sander linkado a partir do post e vale clonar antes da próxima vez que você for escrever um transformador na mão.