Ajout de l'interface Swagger UI à .NET Aspire sur Linux

Installation du package NuGet Swashbuckle

[0:38 - 1:35] Tim ouvre le projet Tiny Ticket dans VS Code et navigue vers le service API de Program.cs. L'API a déjà un point de terminaison GET /api/tickets de l'épisode précédent, mais l'appeler nécessitait de construire manuellement l'URL. Pour ajouter une interface de test appropriée, la première étape consiste à installer le package Swagger UI.

Cliquez avec le bouton droit sur le projet API, sélectionnez "Ajouter un package NuGet" et recherchez Swashbuckle.AspNetCore.SwaggerUI. Tim installe la dernière version (10.1.7 au moment de l'enregistrement). Après l'installation, la référence du package apparaît dans le fichier de projet. Aucune autre dépendance n'est nécessaire car le projet inclut déjà le support OpenAPI via la configuration par défaut du service Aspire.

// Verify the package was added to the .csproj
// <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.1.7" />

// Verify the package was added to the .csproj
// <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.1.7" />

Configuring Swagger UI in Program.cs

[1:35 - 3:12] Avec le package installé, la configuration va dans le bloc de développement seulement de Program.cs. Le projet a déjà app.MapOpenApi() enregistré, qui génère le fichier de spécification OpenAPI à l'exécution. Swagger UI a simplement besoin de savoir où ce fichier se trouve et comment étiqueter le groupe de points de terminaison.

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();

    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "Ticket App API v1");
    });
}

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();

    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "Ticket App API v1");
    });
}

L'appel SwaggerEndpoint pointe vers la spécification OpenAPI que .NET génère automatiquement. Le deuxième paramètre est un nom d'affichage qui apparaît dans le menu déroulant de Swagger UI. Tim souligne que ces trois lignes constituent toute la configuration de Swagger. Vous pouvez ajouter plus de configuration pour personnaliser l'UI, grouper les endpoints, ou ajouter des en-têtes d'authentification, mais pour un outil de test de développement, les valeurs par défaut sont suffisantes.

Un détail à noter : depuis .NET 9, les nouveaux projets API n'incluent plus Swagger par défaut. Microsoft a séparé les préoccupations en livrant OpenAPI comme norme et laissant les développeurs choisir leur couche d'UI préférée. Swagger, Scalar, et d'autres outils consomment tous le même fichier de spécification OpenAPI, donc vous n'êtes pas verrouillé dans un visionneur particulier.

Exécution et vérification de l'interface Swagger

[3:12 - 6:07] Après avoir enregistré, Tim lance le projet via le panneau Exécution et Débogage. Une fois que le tableau de bord Aspire est chargé et que le service API apparaît comme en cours d'exécution, il navigue vers l'URL de l'API et ajoute /swagger au chemin.

L'interface Swagger UI charge avec l'étiquette " Ticket App API v1 " et liste les endpoints disponibles. Le point de terminaison principal (/) retourne un simple message de santé, et /api/tickets retourne les données du ticket depuis la base de données.

Tim clique sur " Essayer " sur le point de terminaison racine et l'exécute. La réponse revient avec un statut 200 et un message de confirmation. Puis il passe au point de terminaison /api/tickets et appuie sur exécuter, là où les problèmes commencent.

La première tentative échoue avec une erreur de connexion : " Une erreur liée au réseau ou spécifique à l'instance s'est produite lors de l'établissement de la connexion au serveur SQL. " Le conteneur de base de données ne s'était pas démarré après un redémarrage de la machine. Tim ouvre Portainer, trouve le conteneur Docker SQL Server, et le démarre. Après que le conteneur a fini de s'initialiser, il retourne à Swagger et exécute la demande à nouveau. Cette fois, la réponse renvoie un 200 avec les trois tickets de test stockés dans la base de données.

Cette séquence rappelle pratiquement que les tests d'intégration contre une infrastructure réelle feront surface des problèmes que les tests unitaires et les données simulées ne peuvent pas. Le conteneur de base de données n'est pas configuré pour démarrer automatiquement au démarrage, ce qui signifie que le premier appel d'API après un redémarrage échouera à moins que vous ne vérifiiez d'abord l'état du conteneur.

Ce qui vient ensuite : Endpoints CRUD

[6:07 - 7:20] Tim présente les épisodes à venir dans la série. L'API Tiny Ticket a actuellement uniquement le point de terminaison GET /api/tickets, qui correspond à la procédure stockée spTickets_GetAll. Les procédures stockées restantes dans la base de données (Get by ID, Insert, Update, Delete) ont chacune besoin d'un point de terminaison API correspondant avec le bon verbe HTTP : GET pour la récupération, POST pour la création, PUT pour les mises à jour, et DELETE pour la suppression.

Il note que chaque point de terminaison suit le même modèle et est simple à mettre en œuvre, mais les vidéos à venir les couvriront individuellement afin que chaque pièce soit facile à référencer de manière indépendante. Le choix de diviser la série en petits épisodes focalisés signifie que vous pouvez passer directement au type de point de terminaison dont vous avez besoin sans parcourir une vidéo plus longue.

Conclusion

[7:20 - 7:24] L'ajout de Swagger UI à un projet .NET Aspire sur Linux nécessite un package NuGet et trois lignes de configuration dans Program.cs. Le fichier de spécification OpenAPI est déjà généré par la configuration par défaut du service Aspire, donc Swagger a simplement besoin d'un pointeur vers ce fichier et d'un nom d'affichage. À partir de là, chaque point de terminaison de l'API est testable via le navigateur sans construire un client séparé.

Le problème de connexion à la base de données rencontré par Tim après le redémarrage renforce un point pratique : lorsque votre pile de développement comprend des conteneurs, vérifiez qu'ils sont en cours d'exécution avant de tester les endpoints d'API. Swagger vous donne une boucle de retour rapide pour cette vérification.

Navigation dans la série : Cet article fait partie de la série C# sur Linux construisant l'application Tiny Ticket. Précédent : Configuration de .NET Aspire sur Linux. Suivant : Ajout d'un point de terminaison Get By ID.

Conseil exemple : Si vous préférez un autre visualiseur OpenAPI à Swagger, installez un package comme Scalar ou RapiDoc et pointez-le vers le même point de terminaison /openapi/v1.json. Le fichier de spécification est indépendant de l'UI, donc vous pouvez changer de visionneurs sans modifier la configuration de votre API.

Regardez la vidéo complète sur sa chaîne YouTube et obtenez plus d'informations sur la création d'API dans la série C# sur Linux.