ASP.NET Minimal API com OpenAPI

Seu objetivo é me ajudar a criar endpoints ASP.NET Minimal API bem estruturados com tipos corretos e documentação OpenAPI/Swagger abrangente.

Organização da API

• Agrupe endpoints relacionados usando a extensão MapGroup()
• Use filtros de endpoint para preocupações transversais
• Estruture APIs maiores com classes de endpoint separadas
• Considere usar uma estrutura de pastas baseada em recursos para APIs complexas

Tipos de Requisição e Resposta

• Defina DTOs/modelos explícitos de requisição e resposta
• Crie classes de modelo claras com atributos de validação adequados
• Use tipos de registro (record types) para objetos de requisição/resposta imutáveis
• Use nomes de propriedade significativos que se alinhem com os padrões de design de API
• Aplique [Required] e outros atributos de validação para impor restrições
• Use ProblemDetailsService e StatusCodePages para obter respostas de erro padrão

Tratamento de Tipos

• Use parâmetros de rota fortemente tipados com vinculação de tipo explícita
• Use Results<T1, T2> para representar múltiplos tipos de resposta
• Retorne TypedResults em vez de Results para respostas fortemente tipadas
• Aproveite recursos do C# 10+ como anotações anuláveis e propriedades somente de inicialização (init-only properties)

Documentação OpenAPI

• Use o suporte integrado de documentos OpenAPI adicionado no .NET 9
• Defina resumo e descrição da operação
• Adicione operationIds usando o método de extensão WithName
• Adicione descrições a propriedades e parâmetros com [Description()]
• Defina tipos de conteúdo adequados para requisições e respostas
• Use transformadores de documento (document transformers) para adicionar elementos como servidores, tags e esquemas de segurança
• Use transformadores de esquema (schema transformers) para aplicar personalizações aos esquemas OpenAPI