Swagger/OpenAPI pour C# (.NET) : Génération et documentation d'API

Génération Swagger/OpenAPI pour C# (.NET)

\n\n

Swagger (maintenant officiellement connu sous le nom d'OpenAPI) est un outil puissant pour concevoir, créer, documenter et utiliser des API RESTful. Dans l'écosystème .NET, la génération de spécifications OpenAPI et de documentation interactive est devenue une partie intégrante du développement de services web modernes. Dans cet article, nous allons voir en détail comment configurer la génération automatique de Swagger/OpenAPI dans les applications C# (.NET) en utilisant la bibliothèque Swashbuckle.AspNetCore.

\n\n

Swagger permet non seulement de créer automatiquement une documentation lisible, mais fournit également une interface interactive (Swagger UI) pour tester les points de terminaison directement depuis le navigateur. Cela accélère considérablement le développement et l'intégration entre les équipes.

\n\n

Installation et configuration de Swashbuckle dans .NET

\n\n

Pour commencer, nous devons installer le paquet Swashbuckle.AspNetCore. C'est le paquet principal qui inclut le générateur Swagger, Swagger UI et l'intégration avec ASP.NET Core.

\n\n

Installation via la console NuGet Package Manager :

\n

Install-Package Swashbuckle.AspNetCore

\n\n

Ou via .NET CLI :

\n

dotnet add package Swashbuckle.AspNetCore

\n\n

Après l'installation du paquet, il est nécessaire de configurer les services dans le fichier Program.cs (ou Startup.cs pour les versions plus anciennes). Voici une configuration minimale pour .NET 8 et versions ultérieures :

\n\n

var builder = WebApplication.CreateBuilder(args);\n\n// Ajout des services Swagger\nbuilder.Services.AddSwaggerGen(c =>\n{\n    c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo\n    {\n        Title = "My API",\n        Version = "v1",\n        Description = "Exemple d'API avec documentation Swagger"\n    });\n});\n\nbuilder.Services.AddControllers();\n\nvar app = builder.Build();\n\nif (app.Environment.IsDevelopment())\n{\n    app.UseSwagger();\n    app.UseSwaggerUI(c =>\n    {\n        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");\n    });\n}\n\napp.UseHttpsRedirection();\napp.MapControllers();\n\napp.Run();

\n\n

Fonctionnalités principales de Swashbuckle

\n\n

\n
• Génération automatique de spécification OpenAPI — la bibliothèque analyse vos contrôleurs, modèles de données et attributs, créant un fichier de spécification JSON/YAML.
\n
• Swagger UI interactif — une interface web où vous pouvez consulter les points de terminaison, envoyer des requêtes et voir les réponses.
\n
• Prise en charge des commentaires XML — si vous ajoutez une documentation XML à vos contrôleurs et modèles, Swagger les affichera dans l'interface.
\n
• Regroupement par versions — vous pouvez créer plusieurs versions de documentation pour différentes versions de l'API.
\n
• Personnalisation — possibilité de configurer l'apparence, d'ajouter des en-têtes, des schémas d'authentification (JWT, Basic Auth) et bien plus encore.
\n

\n\n

Ajout de commentaires XML pour la documentation

\n\n

Pour que votre documentation soit informative, utilisez des commentaires XML. Commencez par activer la génération du fichier XML dans le projet. Ouvrez le fichier .csproj et ajoutez :

\n\n

<PropertyGroup>\n    <GenerateDocumentationFile>true</GenerateDocumentationFile>\n    <NoWarn>$(NoWarn);1591</NoWarn>\n</PropertyGroup>

\n\n

Ensuite, indiquez le chemin vers le fichier XML dans AddSwaggerGen :

\n\n

builder.Services.AddSwaggerGen(c =>\n{\n    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });\n    \n    // Indique le chemin vers le fichier XML de documentation\n    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";\n    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);\n    c.IncludeXmlComments(xmlPath);\n});

\n\n

Maintenant, les commentaires de votre code s'afficheront dans Swagger UI. Exemple de contrôleur avec commentaires :

\n\n

/// <summary>\n