Génération Swagger/OpenAPI pour C# (.NET) : Swashbuckle et NSwag

Génération Swagger/OpenAPI pour C# (.NET) : Swashbuckle et NSwag

La documentation des API REST est une partie essentielle du développement moderne en C# (.NET). La spécification OpenAPI (anciennement connue sous le nom de Swagger) permet de décrire les endpoints, les modèles de données, les paramètres et les réponses dans un format unique et lisible par machine (JSON/YAML). Dans l'écosystème .NET Core / .NET 5+, il existe deux outils principaux pour la génération automatique de spécifications OpenAPI : Swashbuckle.AspNetCore et NSwag. Les deux outils s'intègrent dans ASP.NET Core, analysent votre code et créent une documentation interactive (Swagger UI).

Swashbuckle.AspNetCore : le choix classique

Swashbuckle est le package le plus populaire pour la génération de Swagger/OpenAPI dans .NET. Il construit automatiquement la spécification à partir des contrôleurs, des attributs de routage et des annotations de modèles. Il prend en charge OpenAPI 3.0 et Swagger 2.0.

Installation et configuration de base

dotnet add package Swashbuckle.AspNetCore

Dans le fichier Program.cs (ou Startup.cs pour les anciennes versions), ajoutez les services et le middleware :

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();builder.Services.AddEndpointsApiExplorer();builder.Services.AddSwaggerGen(c =>{    c.SwaggerDoc("v1", new OpenApiInfo    {        Title = "Mon API",        Version = "v1",        Description = "Exemple d'API pour un site éducatif"    });});

var app = builder.Build();

if (app.Environment.IsDevelopment()){    app.UseSwagger();    app.UseSwaggerUI(c =>    {        c.SwaggerEndpoint("/swagger/v1/swagger.json", "Mon API v1");    });}

app.MapControllers();app.Run();

Après le lancement, accédez à l'adresse /swagger — une interface utilisateur interactive s'ouvrira, permettant de tester les endpoints directement depuis le navigateur.

Ajout de commentaires XML

Pour que les descriptions des commentaires XML apparaissent dans la documentation, activez la génération XML dans .csproj :

<PropertyGroup>  <GenerateDocumentationFile>true</GenerateDocumentationFile></PropertyGroup>

Ensuite, spécifiez le chemin vers le fichier XML dans AddSwaggerGen :

builder.Services.AddSwaggerGen(c =>{    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);    c.IncludeXmlComments(xmlPath);});

Désormais, les commentaires du code s'afficheront dans Swagger UI.

Exemple de contrôleur avec annotations

[ApiController][Route("api/[controller]")]public class ProductsController : ControllerBase{    /// <summary>    /// Obtenir la liste de tous les produits    /// </summary>    [HttpGet]    public ActionResult<IEnumerable<Product>> GetAll()    {        return Ok(new List<Product>());    }

    /// <summary>    /// Obtenir un produit par son ID    /// </summary>    /// <param name="id">Identifiant du produit</param>    [HttpGet("{id}")]    public ActionResult<Product> GetById(int id)    {        return Ok(new Product { Id = id, Name = "Exemple" });    }}

NSwag : un outil polyvalent avec génération de clients

NSwag est une alternative plus puissante. En plus de la génération de documentation, il peut créer des clients C# pour l'API, des clients TypeScript, ainsi que générer du code à partir de spécifications OpenAPI externes.

Installation et configuration

dotnet add package NSwag.AspNetCore

Configuration dans Program.cs :

builder.Services.AddOpenApiDocument(config =>{    config.Title = "Mon API (NSwag)";    config.Version = "v1";    config.Description = "API générée avec NSwag";});

// ...