.net Core Swagger Example Response

5 min read Jun 03, 2024

Intégration de Swagger dans une API .NET Core pour une documentation et des exemples de réponse clairs

Introduction

Swagger est un outil puissant pour documenter et tester des API REST. Il permet de générer automatiquement une interface utilisateur interactive qui présente les points de terminaison de l'API, leurs paramètres, leurs réponses attendues et même des exemples de données. Dans cet article, nous allons explorer comment intégrer Swagger dans une application .NET Core et comment fournir des exemples de réponse pour une documentation claire et complète.

Installation et Configuration

Installation du package NuGet: Commencez par installer le package NuGet Swashbuckle.AspNetCore dans votre projet .NET Core. Vous pouvez le faire via la console de gestion de package (PMC) ou en utilisant le gestionnaire de packages NuGet de Visual Studio.
Configuration dans le fichier Startup.cs: Dans la méthode ConfigureServices de votre classe Startup.cs, ajoutez les lignes suivantes pour configurer Swagger:

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "Mon API", Version = "v1" });
});

Ajout de la middleware Swagger: Dans la méthode Configure de votre classe Startup.cs, ajoutez la middleware Swagger pour activer l'interface utilisateur Swagger:

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

Fournir des exemples de réponse

Pour fournir des exemples de réponse avec Swagger, vous pouvez utiliser les annotations [ProducesResponseType] et [Example] de .NET Core.

[HttpGet]
[ProducesResponseType(typeof(Produit), 200)]
[ProducesResponseType(typeof(string), 404)]
public IActionResult GetProduit(int id)
{
    // ... code pour récupérer le produit
    if (produit == null)
    {
        return NotFound("Produit non trouvé");
    }

    return Ok(produit);
}

Dans l'exemple ci-dessus:

[ProducesResponseType(typeof(Produit), 200)] indique que l'API peut renvoyer un objet Produit avec un code de statut 200 (Succès).
[ProducesResponseType(typeof(string), 404)] indique que l'API peut renvoyer un message d'erreur de type string avec un code de statut 404 (Non trouvé).

Vous pouvez également fournir un exemple de réponse spécifique en utilisant l'annotation [Example] :

[HttpGet]
[ProducesResponseType(typeof(Produit), 200, Type = typeof(ProduitExemple))]
public IActionResult GetProduit(int id)
{
    // ... code pour récupérer le produit
    // ...
}

public class ProduitExemple
{
    public int Id { get; set; } = 1;
    public string Nom { get; set; } = "Produit exemple";
    public decimal Prix { get; set; } = 10.99m;
}

Cet exemple utilise la classe ProduitExemple pour définir un exemple de données qui sera affiché dans l'interface utilisateur Swagger.

Conclusion

En intégrant Swagger à votre application .NET Core, vous pouvez facilement documenter votre API REST et fournir des exemples de réponse clairs pour les développeurs qui consomment votre API. Cela permet d'améliorer la communication et la compréhension entre les équipes de développement et les équipes utilisant votre API.

N'oubliez pas que la documentation est un aspect essentiel du développement d'API REST. Swagger est un outil puissant pour simplifier ce processus et garantir une documentation complète et facile à utiliser.