Swashbuckle pour C# (.NET) : guide complet avec exemples

Qu'est-ce que Swashbuckle et pourquoi l'utiliser ?

Swashbuckle est une bibliothèque puissante pour la plateforme .NET qui génère automatiquement une documentation interactive pour vos Web API basée sur la norme OpenAPI (anciennement connue sous le nom de Swagger). Elle s'intègre directement dans les applications ASP.NET Core et permet aux développeurs, testeurs et consommateurs d'API de comprendre et d'interagir facilement avec vos points de terminaison.

Pourquoi en avez-vous besoin ?

• Automatisation de la documentation : Plus besoin de rédiger et de maintenir manuellement la documentation. Swashbuckle analyse vos contrôleurs, modèles et attributs pour créer une documentation à jour en temps réel.
• Interface interactive (Swagger UI) : La bibliothèque fournit une interface web où vous pouvez visualiser tous les endpoints, leurs paramètres, les modèles de données et même exécuter des requêtes de test directement depuis votre navigateur.
• Standardisation : OpenAPI est une norme industrielle. La documentation générée peut être utilisée pour générer automatiquement des SDK clients dans différents langages (JavaScript, Python, Java, etc.).
• Simplification des tests et du débogage : Les développeurs et ingénieurs QA peuvent tester rapidement l'API sans utiliser d'outils externes comme Postman (bien que Postman puisse également importer la spécification OpenAPI).

Swashbuckle se compose de deux composants principaux : Swashbuckle.AspNetCore.Swagger (génération de la spécification JSON OpenAPI) et Swashbuckle.AspNetCore.SwaggerUI (affichage de l'interface interactive).

Installation

Swashbuckle s'installe via le gestionnaire de paquets NuGet. Vous pouvez utiliser la console du gestionnaire de paquets, l'interface CLI .NET ou l'interface Visual Studio.

Via .NET CLI (recommandé)

dotnet add package Swashbuckle.AspNetCore

Via la console du gestionnaire de paquets dans Visual Studio

Install-Package Swashbuckle.AspNetCore

Cette commande installe le paquet principal qui inclut tous les composants nécessaires : Swagger, SwaggerUI et Swashbuckle.Core.

Démarrage rapide avec un exemple de code

Examinons la configuration minimale de Swashbuckle pour une Web API ASP.NET Core.

1. Créez un nouveau projet Web API

dotnet new webapi -n MySwaggerApi
cd MySwaggerApi

2. Ajoutez Swashbuckle

dotnet add package Swashbuckle.AspNetCore

3. Configurez Program.cs

Ouvrez le fichier Program.cs et ajoutez les lignes suivantes :

using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder(args);

// Ajout des services Swagger
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "My Awesome API",
        Version = "v1",
        Description = "Un exemple d'API pour démontrer Swashbuckle"
    });
});

var app = builder.Build();

// Activation du middleware Swagger
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

// Exemple d'endpoint simple
var summaries = new[]
{
    "Gel", "Frais", "Froid", "Tempéré", "Doux", "Chaud", "Agréable", "Très chaud", "Caniculaire", "Torride"
};

app.MapGet("/previsions-meteo", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new PrevisionMeteo
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("GetPrevisionsMeteo");

app.Run();

record PrevisionMeteo(DateOnly Date, int TemperatureC, string? Resume)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

4. Lancez l'application

dotnet run