API minimal ASP.NET avec OpenAPI

Votre objectif est de m'aider à créer des endpoints d'API minimal ASP.NET bien structurés avec les types corrects et une documentation OpenAPI/Swagger complète.

Organisation de l'API

• Groupez les endpoints connexes en utilisant l'extension MapGroup()
• Utilisez les filtres d'endpoint pour les préoccupations transversales
• Structurez les APIs plus grandes avec des classes d'endpoint séparées
• Envisagez une structure de dossiers basée sur les fonctionnalités pour les APIs complexes

Types de requête et réponse

• Définissez des DTOs/modèles explicites pour les requêtes et réponses
• Créez des classes de modèle claires avec les attributs de validation appropriés
• Utilisez les types record pour les objets de requête/réponse immuables
• Utilisez des noms de propriétés significatifs qui s'alignent avec les normes de conception d'API
• Appliquez [Required] et d'autres attributs de validation pour imposer les contraintes
• Utilisez le ProblemDetailsService et StatusCodePages pour obtenir des réponses d'erreur standardisées

Gestion des types

• Utilisez des paramètres de route fortement typés avec liaison de type explicite
• Utilisez Results<T1, T2> pour représenter plusieurs types de réponse
• Renvoyez TypedResults au lieu de Results pour les réponses fortement typées
• Tirez parti des fonctionnalités C# 10+ comme les annotations nullables et les propriétés init-only

Documentation OpenAPI

• Utilisez le support de document OpenAPI intégré ajouté dans .NET 9
• Définissez le résumé et la description de l'opération
• Ajoutez des operationIds en utilisant la méthode d'extension WithName
• Ajoutez des descriptions aux propriétés et paramètres avec [Description()]
• Définissez les types de contenu appropriés pour les requêtes et réponses
• Utilisez des transformateurs de document pour ajouter des éléments comme les serveurs, les tags et les schémas de sécurité
• Utilisez des transformateurs de schéma pour appliquer des personnalisations aux schémas OpenAPI