Comment utiliser Swagger dans ASP.Net Core

Vous voudrez souvent créer de la documentation pour votre API. Pour créer cette documentation, vous pouvez tirer parti de Swagger - un outil qui peut être utilisé pour fournir facilement une représentation de l'interface utilisateur de votre API. Une fois que vous avez généré la documentation Swagger pour votre API, vous pouvez afficher la signature de vos méthodes API et même tester vos méthodes API.

Swashbuckle est un projet open source pour générer des documents Swagger. Cet article présente une discussion sur la façon dont nous pouvons tirer parti de Swashbuckle pour générer une documentation interactive pour notre API RESTful.

Créer un projet ASP.Net Core

Tout d'abord, créons un projet ASP.Net Core dans Visual Studio. En supposant que Visual Studio 2017 ou Visual Studio 2019 est installé sur votre système, suivez les étapes décrites ci-dessous pour créer un nouveau projet ASP.Net Core dans Visual Studio.

  1. Lancez l'IDE de Visual Studio.
  2. Cliquez sur "Créer un nouveau projet".
  3. Dans la fenêtre «Créer un nouveau projet», sélectionnez «Application Web ASP.Net Core» dans la liste des modèles affichés.
  4. Cliquez sur Suivant. 
  5. Dans la fenêtre «Configurer votre nouveau projet» qui s'affiche ensuite, spécifiez le nom et l'emplacement du nouveau projet.
  6. Cliquez sur Créer. 
  7. Dans la fenêtre «Créer une nouvelle application Web ASP.Net Core», sélectionnez .Net Core comme moteur d'exécution et ASP.Net Core 2.2 (ou version ultérieure) dans la liste déroulante en haut.
  8. Sélectionnez «API» comme modèle de projet pour créer un nouveau projet API Web ASP.Net Core. 
  9. Assurez-vous que les cases à cocher «Activer le support Docker» et «Configurer pour HTTPS» ne sont pas cochées car nous n'utiliserons pas ces fonctionnalités ici.
  10. Assurez-vous que l'authentification est définie sur «Aucune authentification» car nous n'utiliserons pas non plus l'authentification.
  11. Cliquez sur Créer.

Suivre ces étapes créera un nouveau projet ASP.Net Core dans Visual Studio. Nous utiliserons ce projet dans les sections suivantes de cet article pour examiner comment nous pouvons générer de la documentation Swagger pour le ValuesController.

Installez le middleware Swagger dans ASP.Net Core

Si vous avez réussi à créer un projet ASP.Net Core, la prochaine chose que vous devez faire est d'ajouter les packages NuGet nécessaires à votre projet. Pour ce faire, sélectionnez le projet dans la fenêtre Explorateur de solutions, cliquez avec le bouton droit de la souris et sélectionnez «Gérer les packages NuGet ....» Dans la fenêtre NuGet Package Manager, recherchez le package Swashbuckle.AspNetCore et installez-le. Vous pouvez également installer le package via la console NuGet Package Manager comme indiqué ci-dessous.

PM> Paquet d'installation Swashbuckle.AspNetCore

Le package Swashbuckle.AspNetCore contient les outils nécessaires pour générer des documents API pour ASP.Net Core.

Configurer le middleware Swagger dans ASP.Net Core

Pour configurer Swagger, écrivez le code suivant dans la méthode ConfigureServices. Notez comment la méthode d'extension AddSwaggerGen est utilisée pour spécifier les métadonnées du document API.

services.AddSwaggerGen (c =>

            {

                c.SwaggerDoc ("v1", nouvelle info

                {

                    Version = "v1",

                    Title = "Démo Swagger",

                    Description = "Démo Swagger pour ValuesController",

                    TermsOfService = "Aucun",

                    Contact = nouveau contact () {Name = "Joydip Kanjilal",

                    Courriel = "[email protected]",

                    Url = "www.google.com"}

                });

            });

Vous devez également activer Swagger UI dans la méthode Configure comme indiqué ci-dessous.

app.UseSwagger ();

app.UseSwaggerUI (c =>

{

   c.SwaggerEndpoint ("/ swagger / v1 / swagger.json", "v1");

});

Voici le code complet de la classe Startup pour votre référence.

en utilisant Microsoft.AspNetCore.Builder;

en utilisant Microsoft.AspNetCore.Hosting;

en utilisant Microsoft.AspNetCore.Mvc;

en utilisant Microsoft.Extensions.Configuration;

using Microsoft.Extensions.DependencyInjection;

en utilisant Swashbuckle.AspNetCore.Swagger;

espace de noms SwaggerDemo

{

    Démarrage de classe publique

    {

        Démarrage public (configuration IConfiguration)

        {

            Configuration = configuration;

        }

        public IConfiguration Configuration {get; }

        public void ConfigureServices (services IServiceCollection)

        {

            services.AddMvc (). SetCompatibilityVersion

            (CompatibilityVersion.Version_2_2);   

            services.AddSwaggerGen (c =>

            {

                c.SwaggerDoc ("v1", nouvelle info

                {

                    Version = "v1",

                    Title = "Démo Swagger",

                    Description = "Démo Swagger pour ValuesController",

                    TermsOfService = "Aucun",

                    Contact = nouveau contact () {Name = "Joydip Kanjilal",

                    Courriel = "[email protected]",

                    Url = "www.google.com"

                }

                });

            });

        }

        public void Configure (application IApplicationBuilder,

       IHostingEnvironment env)

        {

            si (env.IsDevelopment ())

            {

                app.UseDeveloperExceptionPage ();

            }

            app.UseMvc ();

            app.UseSwagger ();

            app.UseSwaggerUI (c =>

            {

                c.SwaggerEndpoint ("/ swagger / v1 / swagger.json", "v1");

            });

        }

    }

}

C'est tout ce que vous devez faire pour démarrer avec Swagger.

Parcourez l'interface utilisateur Swagger de votre application ASP.Net Core

Nous sommes maintenant prêts à exécuter l'application et à parcourir le point de terminaison Swagger. L'interface utilisateur Swagger apparaîtra comme dans la figure 1 ci-dessous. Notez comment Swagger utilise différentes couleurs pour les verbes HTTP GET, PUT, POST et DELETE. Vous pouvez exécuter chacun des points de terminaison illustrés dans la figure 1 directement à partir de l'interface utilisateur de Swagger.

Créez des commentaires XML dans les méthodes d'action de votre contrôleur

Jusqu'ici tout va bien. Dans le document Swagger généré précédemment, il n'y avait pas de commentaires XML. Si vous souhaitez afficher des commentaires XML dans le document Swagger, écrivez simplement ces commentaires dans les méthodes d'action de votre contrôleur.

Écrivons maintenant des commentaires pour chacune des méthodes d'action dans le ValuesController. Voici la version mise à jour de ValuesController avec des commentaires XML pour chacune des méthodes d'action.

  [Route ("api / [contrôleur]")]

    [ApiController]

    public class ValuesController: ControllerBase

    {

        ///

        /// Récupère la méthode d'action sans aucun argument

        ///

        ///

        [HttpGet]

        action publique Avoir()

        {

            retourne une nouvelle chaîne [] {"valeur1", "valeur2"};

        }

        ///

        /// Récupère une méthode d'action qui accepte un entier comme argument

        ///

        ///

        ///

        [HttpGet ("{id}")]

        public ActionResult Get (int id)

        {

            renvoie "valeur";

        }

        ///

        /// Post-action méthode pour ajouter des données

        ///

        ///

        [HttpPost]

        public void Post (valeur de chaîne [FromBody])

        {

        }

        ///

        /// Mettre une méthode d'action pour modifier les données

        ///

        ///

        ///

        [HttpPut ("{id}")]

        public void Put (int id, valeur de chaîne [FromBody])

        {

        }

        ///

        /// Supprimer la méthode d'action

        ///

        ///

        [HttpDelete ("{id}")]

        public void Delete (int id)

        {

        }

    }

Activer les commentaires XML dans Swagger

Notez que Swagger n'affiche pas les commentaires XML par défaut. Vous devez activer cette fonctionnalité. Pour ce faire, cliquez avec le bouton droit sur Projet, sélectionnez Propriétés, puis accédez à l'onglet Générer. Dans l'onglet Construire, cochez l'option «Fichier de documentation XML» pour spécifier l'emplacement où le fichier de documentation XML sera créé.

Vous devez également spécifier que les commentaires XML doivent être inclus lors de la génération du document Swagger en écrivant le code suivant dans la méthode ConfigureServices.

c.IncludeXmlComments (@ "D: \ Projects \\ SwaggerDemo \ SwaggerDemo \ SwaggerDemo.xml");

Et c'est tout ce que vous devez faire pour activer les commentaires XML dans Swagger.

Définissez l'URL de lancement de l'application sur Swagger UI

Vous pouvez modifier l'URL de lancement de votre application pour spécifier que l'interface utilisateur Swagger sera chargée au lancement de l'application. Pour ce faire, cliquez avec le bouton droit sur Projet et sélectionnez Propriétés. Accédez ensuite à l'onglet Déboguer. Enfin, spécifiez la valeur de lancement du navigateur comme swagger, comme illustré dans la figure 2.

Lorsque vous exécutez à nouveau l'application et accédez à l'URL Swagger, vous devriez voir l'interface utilisateur Swagger comme illustré dans la figure 3 ci-dessous. Notez les commentaires XML dans chacune des méthodes API cette fois.

Swashbuckle est un excellent outil pour générer des documents Swagger pour votre API. Plus important encore, Swashbuckle est facile à configurer et à utiliser. Vous pouvez faire beaucoup plus avec Swagger que ce que nous avons vu ici. Vous pouvez personnaliser l'interface utilisateur Swagger à l'aide de feuilles de style en cascade, afficher les valeurs d'énumération sous forme de valeurs de chaîne et créer différents documents Swagger pour différentes versions de votre API, pour n'en nommer que quelques-uns.