Exercice : utiliser Swashbuckle pour créer un document OpenAPI

8 minutes

Dans cet exercice, vous allez ajouter Swagger et l’interface utilisateur Swagger à une application API web ASP.NET Core. Les outils Swagger permettent de créer le document OpenAPI qui décrit votre API web.

Notes

Téléchargez le code source sur votre ordinateur local pour effectuer cet exercice. Après avoir téléchargé le fichier, vous devrez le décompresser.

Télécharger : Application API web ASP.net Core.

Sélectionnez le bouton Télécharger au milieu à droite de l’écran.
Décompressez le fichier exercise.zip.

Ajouter les outils Swagger

Ouvrez Visual Studio et recherchez l’application API web ASP.NET Core.
Dans l’Explorateur de solutions, cliquez avec le bouton de droite sur le projet, puis sélectionnez le menu Gérer les packages NuGet.
Dans Gestionnaire de package NuGet, recherchez Swashbuckle.AspNetCore. Sélectionnez le package et installez-le.

Le package NuGet est maintenant installé. Fermez l’onglet Gestionnaire de package NuGet.

Configurer Swashbuckle pour générer un document OpenAPI

Ouvrez le fichier Startup.cs .

Ajoutez la directive suivante juste au-dessus de la ligne, namespace InventoryManagement.ApiApp.

/* === using directive BEGIN === */
using Microsoft.OpenApi.Models;
/* === using directive END === */

Remplacez tout le code de la méthode ConfigureServices(IServiceCollection) par le code suivant :

    services.AddControllers();

    /* === SwaggerGen BEGIN === */
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "Inventory Management", Version = "v1" });
    });
    /* === SwaggerGen END === */

Dans la méthode Configure(IApplicationBuilder, IWebHostEnvironment), recherchez l’instruction conditionnelle if (env.IsDevelopment()) et remplacez tout ce qui précède cette instruction par le code suivant :
```
    /* === SwaggerUI BEGIN === */
    app.UseSwagger(c =>
    {
        c.PreSerializeFilters.Add((swagger, httpReq) => {
            var server = new OpenApiServer() { Url = $"{httpReq.Scheme}://{httpReq.Host.Value}" };
            swagger.Servers = new List<OpenApiServer>() { server };
        });
    });
    app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "InventoryManagement.ApiApp v1"));
    /* === SwaggerUI END === */
```
Remarque

Il est très important que les points de terminaison Swagger soient activés seulement dans l’environnement de développement. Sinon, il peut exposer votre API au public.

Vous venez de terminer l’activation de la fonctionnalité de document OpenAPI sur votre application API web ASP.NET Core. Enregistrez le fichier Startup.cs. La capture d’écran suivante indique à quoi ressemblent vos modifications.

Générer le fichier de document OpenAPI

Sélectionnez le bouton Déboguer en haut et au milieu de Visual Studio.

Il ouvre automatiquement votre navigateur web et affiche la page de l’interface utilisateur Swagger.

La page d’erreurs 404 peut s’afficher. Dans ce cas, entrez l’URL, https://localhost:<port_number>/swagger, dans la barre d’adresses de votre navigateur. Dans la capture d’écran suivante, l’URL est https://localhost:44371/swagger, par exemple.
Sélectionnez le lien pour ouvrir la page de document OpenAPI.
Le document OpenAPI est affiché à la volée.

Votre application API web ASP.NET Core est maintenant prête à produire le document OpenAPI.

Continuer

Ajouter les outils Swagger

Configurer Swashbuckle pour générer un document OpenAPI

Générer le fichier de document OpenAPI

Commentaires