Intégrer Swagger dans vos API .NET : Un exemple concret
Swagger est un outil puissant qui permet de documenter et de tester vos API RESTful de manière simple et efficace. Sa capacité à générer des interfaces de documentation interactives en se basant sur vos définitions d'API est particulièrement appréciable.
Intégration de Swagger dans un projet .NET
Pour illustrer l'intégration de Swagger dans un projet .NET, nous allons créer un exemple simple avec une API qui expose une ressource "Produits".
Étape 1 : Installation des packages NuGet
Commencez par installer les packages NuGet suivants dans votre projet :
- Swashbuckle.AspNetCore : Permet l'intégration de Swagger dans votre application ASP.NET Core.
- Swashbuckle.AspNetCore.SwaggerUI : Fournit l'interface utilisateur pour interagir avec Swagger.
Étape 2 : Configuration de Swagger
Dans le fichier Startup.cs, configurez Swagger en utilisant le code suivant :
public void ConfigureServices(IServiceCollection services)
{
// ... autres configurations
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo
{
Title = "API des Produits",
Version = "v1"
});
});
}
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
// ... autres configurations
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "API des Produits v1");
});
}
Étape 3 : Définition de votre API
Créez un contrôleur d'API pour gérer les opérations sur les produits :
[ApiController]
[Route("[controller]")]
public class ProduitsController : ControllerBase
{
[HttpGet]
public IEnumerable Get()
{
return new List
{
new Produit { Id = 1, Nom = "Produit 1", Description = "Description du produit 1" },
new Produit { Id = 2, Nom = "Produit 2", Description = "Description du produit 2" }
};
}
}
public class Produit
{
public int Id { get; set; }
public string Nom { get; set; }
public string Description { get; set; }
}
Étape 4 : Lancement de l'application
Exécutez votre application. Vous devriez pouvoir accéder à la documentation Swagger en vous rendant à l'adresse http://localhost:<port>/swagger/index.html.
Exemple de documentation Swagger
En utilisant le code ci-dessus, vous devriez voir une page Swagger avec une section "Produits" qui contient les informations suivantes :
- Endpoint :
/Produits - Méthode : GET
- Description : Retourne une liste de produits
- Réponse : Un tableau de
Produit
Vous pouvez également utiliser l'interface interactive de Swagger pour tester votre API en envoyant des requêtes et en visualisant les réponses.
Valeur de Swagger pour vos API .NET
L'intégration de Swagger dans vos applications .NET vous procure plusieurs avantages :
- Documentation automatique: Swagger génère automatiquement des documents de documentation clairs et précis à partir de votre code, ce qui vous permet de gagner du temps et de garantir la cohérence de votre documentation.
- Interface utilisateur interactive: L'interface utilisateur de Swagger permet à vos développeurs et à vos clients de tester vos API facilement, ce qui facilite le développement et l'intégration.
- Amélioration de la collaboration: Swagger permet une meilleure communication entre les développeurs, les équipes QA et les clients, car il fournit une documentation accessible et facile à comprendre.
En conclusion, Swagger est un outil précieux pour tous les développeurs .NET qui créent des API RESTful. Il facilite la documentation, le test et la collaboration, ce qui améliore la qualité de vos API et la satisfaction de vos utilisateurs.