Documenter une API à l’aide de Swashbuckle
Swashbuckle est un package NuGet qui permet de générer automatiquement la documentation Swagger pour les projets API Web ASP.NET. Swagger est un outil qui permet aux développeurs de concevoir, générer, documenter et consommer des API RESTful. Avec Swashbuckle, vous pouvez facilement ajouter la documentation Swagger à votre projet d’API web en annotant votre code avec des attributs qui décrivent vos points de terminaison, paramètres et réponses d’API. Swashbuckle utilise ensuite ces informations pour générer un fichier JSON Swagger, qui peut être utilisé pour générer une documentation d’API interactive, des kits SDK clients, etc.
Swashbuckle repose sur trois composants principaux :
Swashbuckle.AspNetCore.Swagger : modèle objet et intergiciel (middleware) Swagger permettant d’exposer des objets SwaggerDocument en tant que points de terminaison JSON.
Swashbuckle.AspNetCore.SwaggerGen : générateur Swagger qui crée des objets SwaggerDocument directement à partir de vos itinéraires, contrôleurs et modèles. Ce composant est généralement associé à l’intergiciel du point de terminaison Swagger pour exposer automatiquement un fichier JSON Swagger.
Swashbuckle.AspNetCore.SwaggerUI: version incorporée de l’outil IU Swagger. Il interprète le fichier JSON Swagger afin de créer une expérience enrichie et personnalisable permettant de décrire les fonctionnalités de l’API web. Il intègre des ateliers de test pour les méthodes publiques.
La commande dotnet add suivante installe le package NuGet Swashbuckle :
dotnet add <name>.csproj package Swashbuckle.AspNetCore -v 6.5.0
Ajouter et configurer l’intergiciel (middleware) Swagger
Ajoutez le générateur Swagger à la collection de services dans Program.cs.
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
Remarque
L’appel de AddEndpointsApiExplorer indiqué dans l’exemple précédent est requis uniquement pour les API minimales.
Activez l’intergiciel pour traiter le document JSON généré et l’interface utilisateur de Swagger, également dans Program.cs :
app.UseSwagger();
if (app.Environment.IsDevelopment())
{
app.UseSwaggerUI();
}
Le point de terminaison par défaut de l’interface utilisateur Swagger est http:<hostname>:<port>/swagger.
Remarque
SwaggerUI est très utile dans votre environnement de développement. Elle peut être activée en production mais vous devez prendre en compte toutes les exigences de sécurité pour votre application spécifique avant de le faire.
Personnaliser et étendre la documentation Swagger
Swagger fournit des options pour documenter le modèle objet et personnaliser l’interface utilisateur. L’action de configuration passée à la méthode AddSwaggerGen peut inclure des informations supplémentaires via la classe OpenApiInfo.
L’exemple de code suivant montre comment ajouter des informations à afficher dans la documentation de l’API.
// Add using statement for the OpenApiInfo class
using Microsoft.OpenApi.Models;
builder.Services.AddSwaggerGen(options =>
{
options.SwaggerDoc("v1", new OpenApiInfo
{
Version = "v1",
Title = "Fruit API",
Description = "API for managing a list of fruit their stock status.",
TermsOfService = new Uri("https://example.com/terms")
});
});
L’interface utilisateur Swagger affiche la version et les informations ajoutées :
Vous pouvez regrouper des opérations dans votre API à l’aide de l’option .WithTags. Vous pouvez également ajouter un texte descriptif de l’opération à l’aide de l’option .WithSummary. L’exemple de code suivant montre comment utiliser .WithTags pour regrouper l’opération POST dans un groupe post et un groupe fruit. Le résumé spécifié dans l’option .WithSummary est également ajouté à l’opération.
app.MapPost("/fruits", async (Fruit fruit, FruitDb db) =>
{
db.Fruits.Add(fruit);
await db.SaveChangesAsync();
return Results.Created($"/{fruit.Id}", fruit);
})
.Produces<Fruit>(201)
.WithTags("post", "fruits")
.WithSummary("Create a new fruit");
L’interface utilisateur Swagger affiche le regroupement spécifié et une brève description.
