Validação em Minimal APIs no .NET 10

Por que a validação em Minimal APIs importa

Até o .NET 9, validar dados em Minimal APIs exigia código manual ou soluções alternativas. Em outras palavras, cada endpoint precisava conferir os dados recebidos antes de seguir com a lógica de negócio.

Com o suporte embutido, você declara as regras direto em parâmetros de rota, query string, cabeçalhos e corpo da requisição. Tudo isso usando os já conhecidos Data Annotations.

Na prática, a validação em Minimal APIs protege o endpoint de entradas inválidas. Assim, o handler recebe apenas dados que já passaram pelas regras definidas, e você escreve menos código defensivo.

Se você está começando agora, o artigo sobre Minimal APIs no ASP.NET apresenta os fundamentos desse modelo de construção de APIs.

O que são Data Annotations

Os Data Annotations são atributos do namespace System.ComponentModel.DataAnnotations. Eles aplicam regras de validação e metadados direto sobre propriedades e parâmetros no C#.

Esses atributos garantem que os dados recebidos estejam no formato esperado antes de qualquer lógica rodar. Por isso, eles aparecem em praticamente todo projeto ASP.NET Core.

Por exemplo, o atributo [Required] garante que um valor não seja nulo ou vazio. Já o [Range(1, 100)] assegura que o valor fique dentro de um intervalo específico.

Para usá-los, basta decorar o parâmetro do endpoint ou a propriedade de uma classe com os atributos desejados. Em seguida, o ASP.NET Core valida os dados e retorna um erro 400 com os detalhes quando as regras não são atendidas.

using System.ComponentModel.DataAnnotations;

public class UserInput
{
    [Required]
    public string Name { get; set; } = string.Empty;

    [EmailAddress]
    [Required]
    public string Email { get; set; } = string.Empty;
}

Essa abordagem reduz código repetitivo. Além disso, ela mantém as validações centralizadas e consistentes, porque a regra fica junto do modelo que ela protege.

Data Annotations e Minimal APIs antes do .NET 10

Antes do .NET 10, você até podia decorar os modelos de uma Minimal API com Data Annotations. Contudo, o pipeline das Minimal APIs não aplicava a validação automaticamente, como acontece nos controllers com o atributo [ApiController].

app.MapPost("/users", (UserInput input) =>
{
    var context = new ValidationContext(input);
    var results = new List<ValidationResult>();

    // Validação manual, necessária antes do .NET 10
    if (!Validator.TryValidateObject(input, context, results, validateAllProperties: true))
    {
        var errors = results
            .GroupBy(r => r.MemberNames.FirstOrDefault() ?? string.Empty)
            .ToDictionary(g => g.Key, g => g.Select(r => r.ErrorMessage ?? "Invalid value.").ToArray());

        return Results.ValidationProblem(errors);
    }

    return Results.Created($"/users/{input.Email}", input);
});

Como funciona a validação em Minimal APIs no .NET 10

O .NET 10 trouxe o método AddValidation, que registra a validação em Minimal APIs como recurso nativo. Segundo as novidades do ASP.NET Core no .NET 10, o runtime passa a validar os dados antes de chamar o handler.

Ao habilitar o recurso, o ASP.NET Core faz o seguinte.

• Valida dados vindos da query string, dos cabeçalhos e do corpo da requisição.
• Aplica atributos como [Required], [Range] e [EmailAddress].
• Permite regras complexas com IValidatableObject ou atributos personalizados.
• Retorna um 400 Bad Request com os detalhes dos erros quando a validação falha.

Por trás dos panos, o recurso usa um source generator. Ele descobre, em tempo de compilação, os tipos usados nos handlers das Minimal APIs e gera os metadados de validação.

Em seguida, o framework adiciona um endpoint filter a cada endpoint compatível. Esse filtro executa a validação e interrompe a requisição antes do handler quando encontra erros.

var builder = WebApplication.CreateBuilder(args);

// Ativa a validação automática dos endpoints
builder.Services.AddValidation();

var app = builder.Build();

public record Product(
    [Required] string Name,
    [Range(1, 1000)] int Quantity);

app.MapPost("/products", (Product product) =>
{
    // Só chega aqui se o produto for válido
    return TypedResults.Ok(product);
});

public record OrderItem(
    [Required] string Sku,
    [Range(1, 50)] int Quantity);

public record Order(
    [Required] string CustomerEmail,
    [MinLength(1)] List<OrderItem> Items);

app.MapPost("/orders", (Order order) => TypedResults.Created($"/orders/{Guid.NewGuid()}", order));

app.MapGet("/orders", (
    [FromQuery, Range(1, 100)] int pageSize,
    [FromHeader(Name = "X-Tenant-Id"), Required] string tenantId) =>
{
    // pageSize e tenantId já chegam validados
    return TypedResults.Ok(new { pageSize, tenantId });
});

Exemplo prático com atributo personalizado

Você também pode aplicar atributos diretamente nos parâmetros da Minimal API. O exemplo a seguir, inspirado na documentação oficial, usa um atributo personalizado chamado EvenNumber.

app.MapPost("/products",
    ([EvenNumber(ErrorMessage = "Product ID must be even")] int productId, [Required] string name)
        => TypedResults.Ok(productId));

Nesse exemplo, productId precisa ser um número par, regra garantida pelo atributo EvenNumber. Além disso, name é obrigatório por causa do [Required].

Se qualquer um desses requisitos falhar, a API retorna uma resposta 400 com os erros de validação. O atributo EvenNumber não existe no framework, então você precisa criá-lo, como mostra a próxima seção.

using System.ComponentModel.DataAnnotations;

[AttributeUsage(AttributeTargets.Parameter | AttributeTargets.Property)]
public sealed class EvenNumberAttribute : ValidationAttribute
{
    public override bool IsValid(object? value)
    {
        // Valores nulos ficam a cargo do [Required]
        if (value is null)
            return true;

        return value is int number && number % 2 == 0;
    }
}

Desativando a validação em Minimal APIs por endpoint

Quer controle total? Você pode desativar a validação em Minimal APIs para endpoints individuais com o método DisableValidation.

app.MapPost("/products",
    ([EvenNumber(ErrorMessage = "Product ID must be even")] int productId, [Required] string name)
        => TypedResults.Ok(productId))
    .DisableValidation();

Esse recurso é útil quando você quer validar manualmente ou criar um comportamento customizado. Por exemplo, um endpoint de importação em lote pode aceitar registros parcialmente inválidos e devolver um relatório.

Validações avançadas

Além dos atributos padrão do namespace System.ComponentModel.DataAnnotations, você tem duas opções para regras mais elaboradas. Primeiro, criar atributos próprios herdando de ValidationAttribute, como no exemplo anterior.

A segunda opção é implementar a interface IValidatableObject. Ela serve para regras que dependem de várias propriedades ao mesmo tempo ou de condições de negócio.

using System.ComponentModel.DataAnnotations;

public record Booking(
    [Required] string GuestName,
    DateOnly CheckIn,
    DateOnly CheckOut) : IValidatableObject
{
    public IEnumerable<ValidationResult> Validate(ValidationContext validationContext)
    {
        // Regra que envolve duas propriedades
        if (CheckOut <= CheckIn)
        {
            yield return new ValidationResult(
                "Check-out must be after check-in.",
                [nameof(CheckOut)]);
        }
    }
}

Com esse modelo, o endpoint que recebe um Booking rejeita reservas com datas invertidas antes de executar o handler. Assim, a regra de negócio fica no próprio tipo, perto dos dados que ela valida.

Personalizando as respostas de erro

As respostas de erro da validação em Minimal APIs seguem o formato de Problem Details. Além disso, no .NET 10 você pode personalizá-las registrando uma implementação de IProblemDetailsService.

builder.Services.AddProblemDetails(options =>
{
    options.CustomizeProblemDetails = context =>
    {
        // Acrescenta um identificador de rastreamento em toda resposta de erro
        context.ProblemDetails.Extensions["traceId"] = context.HttpContext.TraceIdentifier;
    };
});

builder.Services.AddValidation();

Com isso, os erros de validação ficam consistentes com os demais erros da API. O artigo sobre Problem Details e a RFC 9457 no .NET 10 aprofunda esse formato.

Testando a validação em Minimal APIs

Para ver o recurso em ação, envie uma requisição inválida ao endpoint de produtos. No exemplo abaixo, o nome está vazio e a quantidade está fora do intervalo permitido.

curl -X POST https://localhost:5001/products \
  -H "Content-Type: application/json" \
  -d '{ "name": "", "quantity": 0 }'

Como resposta, a API devolve o status 400 com um corpo no formato de Problem Details. A propriedade errors agrupa as mensagens por campo, o que facilita exibir os erros no front-end.

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "Name": [ "The Name field is required." ],
    "Quantity": [ "The field Quantity must be between 1 and 1000." ]
  }
}

Os textos exatos podem variar conforme a versão e a cultura configurada. Ainda assim, a estrutura com title, status e errors se mantém, então o cliente pode confiar nela.

Também vale cobrir esse comportamento com testes de integração. Assim, uma mudança acidental no registro do AddValidation não passa despercebida, já que a falha de metadados é silenciosa.

Validação nativa ou FluentValidation

A chegada da validação em Minimal APIs não torna as bibliotecas externas obsoletas. Na verdade, cada abordagem atende melhor a um tipo de cenário.

A validação nativa brilha em regras declarativas e simples, como obrigatoriedade, tamanho e formato. Além disso, ela não exige dependências extras e já se integra ao Problem Details.

Por outro lado, o FluentValidation favorece regras condicionais extensas, validações assíncronas e reaproveitamento de validadores entre camadas. Nesses casos, separar as regras do modelo pode deixar o código mais legível.

Portanto, comece pela validação nativa e só adote uma biblioteca quando as regras realmente exigirem. Essa escolha mantém o projeto mais enxuto e reduz o número de pacotes a atualizar.

Cuidados com a validação em Minimal APIs

O source generator só descobre tipos validáveis no assembly onde você chama AddValidation. Portanto, se os endpoints ou modelos ficam em outro projeto, chame AddValidation também a partir desse assembly.

A documentação recomenda criar um método de extensão em cada biblioteca que declara tipos validáveis. Depois, o projeto principal chama esses métodos junto com o seu próprio AddValidation.

namespace Catalog.Extensions;

public static class ServiceCollectionExtensions
{
    // Executa o source generator no assembly da biblioteca
    public static IServiceCollection AddCatalogValidation(this IServiceCollection services)
        => services.AddValidation();
}

Outro ponto importante: quando os metadados não são gerados, nenhuma exceção ou log aparece. Nesse caso, a entrada inválida simplesmente chega ao handler, o que torna o problema silencioso.

Também vale saber que, no .NET 10, algumas APIs de baixo nível do pacote Microsoft.Extensions.Validation são experimentais. No entanto, o AddValidation e o filtro de validação embutido continuam estáveis.

Por fim, a validação de entrada não substitui o tratamento global de exceções. Para os erros inesperados, veja o artigo sobre IExceptionHandler no .NET 10.

Conclusão

Com o suporte oficial, a validação em Minimal APIs deixa o modelo minimalista ainda mais completo e produtivo. Você ganha simplicidade na definição dos endpoints sem abrir mão da robustez no tratamento dos dados de entrada.

Se você ainda não usa Minimal APIs no seu projeto ASP.NET Core, talvez agora seja a hora certa de considerar. Afinal, com menos código, mais clareza e validação embutida, elas entregam poder com elegância.

FAQ

Em qual versão do .NET a validação em Minimal APIs ficou nativa?

No .NET 10. Antes disso, era preciso validar manualmente ou usar bibliotecas e filtros próprios.

Preciso instalar algum pacote para usar AddValidation?

Em projetos web com o SDK Microsoft.NET.Sdk.Web, não. Bibliotecas de classe comuns que declaram tipos validáveis precisam referenciar o pacote Microsoft.Extensions.Validation.

Qual status HTTP a API retorna quando a validação falha?

Ela retorna 400 Bad Request, com os detalhes dos erros no formato de Problem Details.

Posso continuar usando FluentValidation?

Sim. A validação nativa não impede o uso de bibliotecas externas, e você pode desativá-la por endpoint com DisableValidation.

A validação funciona com records?

Sim. Os atributos de Data Annotations nos parâmetros de um record são aplicados da mesma forma que nas propriedades de uma classe.