Créer la documentation des Web API ASP.NET Core avec Swagger

Les nombreux services et applications que nous utilisons au quotidien consomment des API pour offrir les services attendus. Une API (Application Programming Interface), selon Wikipedia, « est un ensemble normalisé de classes, de méthodes ou de fonctions qui sert de façade par laquelle un logiciel offre des services à d'autres logiciels. Elle est offerte par une bibliothèque logicielle ou un service web, le plus souvent accompagnée d'une description qui spécifie comment des programmes consommateurs peuvent se servir des fonctionnalités du programme fournisseur. »

L'API a donc pour vocation d'être exploitée par une autre application. Son utilisation par les développeurs sera plus simple s'il est mis à la disposition de ceux-ci une documentation conviviale et à jour, permettant de savoir le type de requête HTTP utilisé pour consommer une fonctionnalité du service, le type de données qui est passé en paramètre, le type de données qui est retourné, comment tester le service, etc.

C'est pour répondre à ce besoin que des développeurs ont mis en place le projet Swagger. Il s'agit d'un Framework qui offre des outils permettant de générer de la documentation pour son API Web. Il offre également une interface permettant d'explorer et tester les différentes opérations offertes par le service.

Le recours à un tel outil offre de nombreux avantages au développeur :

• la documentation est automatiquement générée à partir du code ;
• cette dernière suit le même cycle de vie que le code : tout changement au code est directement appliqué à la documentation ;
• la documentation est étroitement liée au code et directement livrée avec ce dernier ;
• le développeur n'a plus besoin de mettre des efforts dans la production et l'évolution de la documentation. Cela lui permet donc de se concentrer dans la mise en place de ses API.

Dans le cadre de cet article, nous verrons comment utiliser Swagger pour créer la documentation et tester une Web API ASP.NET Core.

La bonne compréhension de cet article nécessite des connaissances de base dans le développement des API RestFull en utilisant ASP.NET Core Web API.

Pour mettre en place le projet de démonstration, j'ai utilisé les outils suivants :

• .NET Core 2.0 ;
• ASP.NET Core 2.0 ;
• Swashbuckle.AspNetCore 1.0 ;
• Visual Studio Code ;
• Le navigateur Microsoft Edge.

Vous devez obligatoirement avoir le SDK .NET Core 2.0 installé sur votre ordinateur. Vous pouvez utiliser Visual Studio Code ou tout autre éditeur de code de votre choix. Idem pour le navigateur.

Vous pouvez télécharger le code de l'application de démarrage sur ma page GitHub, à l'adresse suivante : https://github.com/hinault/SwaggerDemo/tree/Initial

Cette application dispose d'une Web API permettant de manipuler les informations sur des clients (Customers). Cette API peut être appelée par toute autre application pour ajouter, lister, modifier et supprimer. Elle est donc constituée d'une classe entité (Customer.cs), contenue dans le dossier Models, avec le code suivant :

public class Customer
    {
        public int Id { get; set; }
        public string FirstName { get; set; }
        public string LastName { get; set; }
        public string EMail { get; set; }
    }

Elle dispose également d'un contrôleur (CustomersController.cs), qui implémente les actions qui seront exécutées via des requêtes HTTP (Get, Post, Put et Delete). Le code de ce dernier est le suivant :

[Produces("application/json")]
    [Route("api/Customers")]
    public class CustomersController : Controller
    {
 
        List<Customer> Customers = new List<Customer>
       {
            new Customer { Id = 1, FirstName = "Hinault", LastName = "Romaric", EMail = "hr@gmail.com"},
            new Customer { Id = 2, FirstName = "Thomas", LastName = "Perrin", EMail = "thomas@outlook.com"},
            new Customer { Id = 3, FirstName = "Allan", LastName = "Croft", EMail = "allan.croft@crt.com"},
            new Customer { Id = 3, FirstName = "Sahra", LastName = "Parker", EMail = "sahra@yahoo.com"},
       };
 
        // GET: api/Customers
        [HttpGet]
        public IEnumerable<Customer> GetAll()
        {
            return Customers;
        }
 
        // GET: api/Customers/5
        [HttpGet("{id}", Name = "GetById")]
        public IActionResult GetById(int id)
        {
            var custormer = Customers.FirstOrDefault(c => c.Id == id);
            if (custormer == null)
            { return NotFound(); }
            return new ObjectResult(custormer);
        }
        
        // POST: api/Customers
        [HttpPost]
        public IActionResult Create([FromBody]Customer customer)
        {
            if(customer==null)
            {
                return BadRequest();
            }
 
            Customers.Add(customer);
 
            return CreatedAtRoute("GetById", new { id = customer.Id }, customer);
 
        }
        
        // PUT: api/Customers/5
        [HttpPut("{id}")]
        public IActionResult Update(int id, [FromBody]Customer customer)
        {
 
            if (customer== null || customer.Id != id)
            {
                return BadRequest();
            }
 
            var existingCustomer = Customers.FirstOrDefault(t => t.Id == id);
            if (customer == null)
            {
                return NotFound();
            }
 
            Customers.Remove(existingCustomer);
            Customers.Add(customer);
            return new NoContentResult();
        }
        
        // DELETE: api/ApiWithActions/5
        [HttpDelete("{id}")]
        public IActionResult Delete(int id)
        {
            var customer = Customers.FirstOrDefault(t => t.Id == id);
            if (customer == null)
            {
                return NotFound();
            }
 
           Customers.Remove(customer);
         return new NoContentResult();
        }
    }

Une fois l'application d'exemple téléchargée, vous pouvez l'exécuter en utilisant la commande « Dotnet run » dans le dossier racine du projet (celui contenant le fichier .csproj). Votre navigateur par défaut sera automatiquement lancé avec un onglet exécutant l'application. Ajoutez « /api/Customers » à la suite de ce lien. Vous obtiendrez la liste des clients au format JSON.

Lançons-nous sans plus tarder dans le vif du sujet qui nous intéresse.

L'intégration de Swagger à son application consiste en l'installation du package NuGet Swashbuckle.AspNetCore. Ce package permet l'ajout de trois composants à votre application :

• Swashbuckle.AspNetCore.Swagger : ce composant permet d'exposer les objets SwaggerDocument comme une API JSON. Ce dernier utilise une implémentation de ISwaggerProvider pour générer des documents Swagger qui seront par la suite sérialisés en données JSON ;
• Swashbuckle.AspNetCore.SwaggerGen : ce composant utilise le conteneur d'injection de dépendances de ASP.NET Core pour enregistrer une implémentation de ISwaggerProvider. Elle sera utilisée pour générer des SwaggerDocument, en fonction du contrôleur, de la route et du modèle de données ;
• Swashbuckle.AspNetCore.SwaggerUI : composant utilisé pour générer une version intégrée de swagger-ui. Il s'agit d'une interface utilisateur qui consomme un Endpoint d'API retournant des données Swagger au format JSON. Ce composant exploite ces données pour offrir une documentation interactive, qui permettra en plus de tester le service.

Pour installer Swashbuckle.AspNetCore, vous devez utiliser le terminal intégré de Visual Studio Code ou l'invite de commande (dans le dossier contenant le fichier .csproj) et exécuter la commande suivante :

dotnet add package Swashbuckle.AspNetCore

Une fois le package installé, vous devez configurer votre application pour utiliser ce dernier. La configuration de Swagger se fait en deux étapes :

• l'enregistrement du service dans le « services collection » ;
• l'intégration du middleware Swagger dans le pipeline du Framework.

Suite à l'installation du package Swashbuckle.AspNetCore, une nouvelle extension a été ajoutée pour permettre l'enregistrement du générateur de la documentation Swagger dans la liste des services.

Pour enregistrer le service, vous devez éditer le fichier Startup.cs et modifier la méthode ConfigureServices. À l'enregistrement du service, vous devez définir la version de votre API, ainsi que le titre :

public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc();
 
            services.AddSwaggerGen(c =>
          {
              c.SwaggerDoc("v1", new Info { Title = "SwaggerDemo", Version = "v1" });
           });
        }

L'utilisation de la classe Info nécessite l'ajout du using suivant dans le fichier Startup.cs :

using Swashbuckle.AspNetCore.Swagger;

Passons maintenant à l'intégration du middleware dans le pipeline ASP.NET Core Web API. Ce dernier va permettre de générer la documentation Swagger comme un Endpoint JSON. Concrètement, la saisie du lien suivant http://monapplication/swagger/v1/swagger.json dans votre navigateur lorsque votre application est en cours d'exécution, va permettre d'afficher un document JSON.

Vous allez éditer le fichier Startup.cs, modifier la méthode Configure et ajouter la ligne de code suivante au début de celle-ci :

app.UseSwagger();

Si vous exécutez votre application, vous allez obtenir le résultat suivant :

Le développeur qui utilisera cette API, en exploitant ce lien, sera en mesure de savoir que j'ai une API Customers qui permet de retourner des items de type Customer dans une liste (array), suite à une requête GET.

Pour exploiter correctement les informations retournées par Swagger, le développeur doit donc être en mesure de lire le document JSON qui est retourné. Pour lui faciliter la tâche, vous pouvez utiliser swagger-ui. Ce dernier interprète directement le document JSON retourné par le Endpoint Swagger et affiche ce dernier dans une interface conviviale. De plus, à partir de cette interface, l'utilisateur pourra directement tester votre API.

Pour ajouter le middleware swagger-ui à votre application, vous devez ajouter le code suivant dans la méthode Configure de la classe Startup.

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

Le code complet de cette méthode devrait ressembler à ceci :

   public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
             app.UseSwagger();
 
             app.UseSwaggerUI(c =>
             {
               c.SwaggerEndpoint("/swagger/v1/swagger.json", "SwaggerDemo v1");
             });
 
            app.UseMvc();
           
        }

Si vous exécutez votre application, et saisissez le lien http://monapplication/swagger/ dans votre navigateur, vous allez obtenir le résultat suivant :

Le document affiché est interactif. Vous pouvez donc directement interagir à partir de cette interface et effectuer des requêtes sur l'API. Si vous cliquez par exemple sur la seconde méthode GET de la liste. Vous aurez un formulaire affichant l'ID du client à retourner. Au clic sur « Try it out! », la réponse retournée par l'API est affichée :

Si vous apportez une mise à jour à votre application et publiez une seconde version de votre API, vous pouvez générer une seconde documentation Swagger pour la version 2, tout en maintenant la documentation de la version précédente. Pour ce faire, vous devez simplement ajouter une nouvelle documentation au générateur Swagger :

services.AddSwaggerGen(c =>
          {
             c.SwaggerDoc("v1", new Info { Title = "SwaggerDemo", Version = "v1" });
 
              c.SwaggerDoc("v2", new Info
             {
                Version = "v2",
                Title = "SwaggerDemo API",
                Description = "Customers API to demo Swagger",
                TermsOfService = "None",
                Contact = new Contact 
                { 
                    Name = "Hinault Romaric", 
                    Email = "hinault@monsite.com", 
                    Url = "http://rdonfack.developpez.com/"
                },
                License = new License
                 { 
                     Name = "Apache 2.0", 
                     Url = "http://www.apache.org"
                 }
            });
 
           });

Comme vous pouvez le constater avec le code ci-dessous. La classe Info contient plusieurs autres propriétés. J'ai donc utilisé celles-ci pour offrir une description plus complète de mon API, avec des informations supplémentaires comme la licence, les termes d'utilisation, etc.

Lorsque vous générez plusieurs documentations pour votre API, vous devez ternir compte des éléments suivants :

• Le premier argument de la méthode SwaggerDoc doit permettre d'identifier la documentation. Il doit donc être unique. Couramment, il s'agit du numéro de version (v1, v2, etc.). Cet argument doit être URI-friendly. Il est également utilisé pour le chemin d'accès au document JSON correspondant. Pour notre cas, la documentation de la V1 sera accessible à partir du lien « /swagger/v1/swagger.json » et celle de la V2 à partir du lien « /swagger/v2/swagger.json ».
• Les actions à exclure dans la documentation de la v1 et à inclure uniquement dans la documentation de la v2 doivent être décorées avec l'attribut [ApiExplorerSettings(GroupName = « v2 »)] :

    [HttpDelete("{id}")]
        [ApiExplorerSettings(GroupName = "v2")]
        public IActionResult Delete(int id)
        {
            var customer = Customers.FirstOrDefault(t => t.Id == id);
            if (customer == null)
            {
                return NotFound();
            }
 
           Customers.Remove(customer);
         return new NoContentResult();
        }

Une fois que vous avez modifié le générateur Swagger pour générer plusieurs documentations, vous devez également apporter une modification au middleware SwaggerUI pour que ces documentations soient prises en compte au niveau de l'interface graphique.

Pour ce faire, vous devez simplement spécifier les différents endpoints de vos documentations lorsque vous ajoutez le middleware :

  app.UseSwaggerUI(c =>
             {
               c.SwaggerEndpoint("/swagger/v1/swagger.json", "SwaggerDemo v1");
                c.SwaggerEndpoint("/swagger/v2/swagger.json", "SwaggerDemo v2");
             });

Désormais, lorsque vous accéderez à l'interface utilisateur de Swagger, vous aurez à droite au-dessus une liste déroulante qui vous permettra de switcher entre les différentes documentations.

Par défaut, Swagger génère chaque réponse dans la documentation avec le code 200 et pour description « Success ». Il s'agit du code standard utilisé pour une requête HTTP réussie. Toutefois, Swagger est capable de fournir un document plus complet pour une réponse d'une action. Si l'action retourne un DTO, par exemple, alors il sera automatiquement utilisé pour générer un schéma pour le corps de la réponse.

Par exemple, pour l'action suivante :

[HttpGet]
        public IEnumerable<Customer> GetAll()
        {
            return Customers;
        }

Swagger produit la réponse suivante :

Pour une méthode d'action qui retourne un IActionResult au lieu d'un DTO, Swagger ne sera pas en mesure de générer une réponse explicite. Il générera simplement un code 200, avec la description succès.

Par exemple, pour la méthode d'action suivante :

  [HttpGet("{id}", Name = "GetById")]
  public IActionResult GetById(int id)
        {
            var custormer = Customers.FirstOrDefault(c => c.Id == id);
            if (custormer == null)
            { return NotFound(); }
            return new ObjectResult(custormer);
        }

Swagger va produire dans la documentation la réponse suivante :

"responses": 
           {
              "200": 
                     {
                           "description": "Success"
                      }
            }

Pourtant, c'est un objet (un DTO) de type Custormer qui est encapsulé dans la réponse HTTP. Pour remédier à cela et permettre à l'utilisateur de savoir le type de données qui est retourné dans la réponse, vous pouvez décorer la méthode d'action avec l'attribut [ProducesResponseType] comme suit :

[HttpGet("{id}", Name = "GetById")]
        [ProducesResponseType(typeof(Customer), 200)]
        public IActionResult GetById(int id)
        {
            var custormer = Customers.FirstOrDefault(c => c.Id == id);
            if (custormer == null)
            { return NotFound(); }
            return new ObjectResult(custormer);
        }

Et l'on va obtenir comme résultat ce qui suit :

Si plusieurs réponses différentes peuvent être retournées pour votre méthode d'action, vous pouvez utiliser cet attribut pour décrire ces différentes réponses.

Par exemple, pour la méthode d'action ci-dessus, s'il n'existe aucun client ayant l'ID passé en paramètre, nous aurons un NotFound() comme réponse. Par ailleurs, si le service n'est pas disponible, nous aurons l'erreur HTTP 500, pour « Internal Server Error ».

Pour spécifier cela dans notre documentation Swagger, nous allons utiliser l'attribut [ProducesResponseType] comme suit :

  [HttpGet("{id}", Name = "GetById")]
        [ProducesResponseType(typeof(Customer), 200)]
        [ProducesResponseType(typeof(NotFoundResult), 404)]
        [ProducesResponseType(typeof(void), 500)]
        public IActionResult GetById(int id)
        {
            var custormer = Customers.FirstOrDefault(c => c.Id == id);
            if (custormer == null)
            { return NotFound(); }
            return new ObjectResult(custormer);
        }

Ce qui va produire le résultat suivant :

Dans le code, au début de chaque méthode ou classe, les commentaires XML sont couramment utilisés pour donner une brève description de la méthode ou classe. Ces commentaires peuvent être utilisés par Swagger pour enrichir le contenu de la documentation qui est générée. La prise en compte des commentaires XML se fait en quatre étapes :

1. Inclure les commentaires XML dans vos méthodes d'action :

  /// <summary>
        /// Retourne un client specifique à partir de son id
        /// </summary>
        /// <remarks>Je manque d'imagination</remarks>
        /// <param name="id">id du client a retourné</param>   
        /// <response code="200">client selectionné</response>
        /// <response code="404">client introuvable pour l'id specifié</response>
        /// <response code="500">Oops! le service est indisponible pour le moment</response>
        [HttpGet("{id}", Name = "GetById")]
        [ProducesResponseType(typeof(Customer), 200)]
        [ProducesResponseType(typeof(NotFoundResult), 404)]
        [ProducesResponseType(typeof(void), 500)]
        public IActionResult GetById(int id)
        {
            var custormer = Customers.FirstOrDefault(c => c.Id == id);
            if (custormer == null)
            { return NotFound(); }
            return new ObjectResult(custormer);
        }

1. Modifier les propriétés du projet pour permettre la génération du fichier XML de documentation.

Pour ce faire, vous devez éditer le fichier .csproj et ajouter le contenu XML suivant :

<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
    <DocumentationFile>bin\Debug\netcoreapp2.0\SwaggerDemo.xml</DocumentationFile>
  </PropertyGroup>

Une fois cela fait, si vous procédez à la génération de votre application, un fichier SwaggerDemo.xml sera créé dans le dossier de génération de cette dernière (\bin\Debug\netcoreapp2.0). Son contenu est le suivant :

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>SwaggerDemo</name>
    </assembly>
    <members>
        <member name="M:SwaggerDemo.Controllers.CustomersController.GetById(System.Int32)">
            <summary>
            Retourne un client specifique à partir de son id
            </summary>
            <remarks>Je manque d'imagination</remarks>
            <param name="id">id du client a retourné</param>   
            <response code="200">client selectionné</response>
            <response code="404">client introuvable pour l'id specifié</response>
            <response code="500">Oops! le service est indisponible pour le moment</response>
        </member>
    </members>
</doc>

<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
    <DocumentationFile>bin\Debug\netcoreapp2.0\SwaggerDemo.xml</DocumentationFile>
    <NoWarn>1591</NoWarn>
  </PropertyGroup>

1. Modifier la configuration de Swashbuckle pour exploiter le fichier XML généré.

Vous devez éditer le fichier Startup.cs et modifier la configuration de Swashbuckle pour qu'il puisse inclure le document XML généré dans la documentation :

services.AddSwaggerGen(c =>
          {
             c.SwaggerDoc("v1", new Info { Title = "SwaggerDemo", Version = "v1" });
 
              var filePath = Path.Combine(PlatformServices.Default.Application.ApplicationBasePath, "SwaggerDemo.xml");
 
              c.IncludeXmlComments(filePath);
 
          });

1. Exécutez votre application et accédez au endpoint JSON Swagger pour visualiser le résultat :

Dans l'interface swagger-ui, on obtient ce qui suit :

Lorsqu'une action ou une propriété du modèle est décorée avec l'attribut [Obsolete], Swagger affiche automatiquement un message d'avertissement pour la méthode d'action :

Si vous souhaitez continuer à intégrer ces dernières dans votre documentation sans aucun avertissement, vous pouvez utiliser les méthodes IgnoreObsoleteActions() et IgnoreObsoleteProperties() lors de la configuration de Swagger comme suit :

services.AddSwaggerGen(c =>
          {
             c.SwaggerDoc("v1", new Info { Title = "SwaggerDemo", Version = "v1" });
 
             c.IgnoreObsoleteActions();
             c.IgnoreObsoleteProperties();
          });

Pour exclure une méthode d'action, vous devez décorer cette dernière avec l'attribut ApiExplorerSettings, comme suit :

[HttpGet]
        [ApiExplorerSettings(IgnoreApi = true)]
        public IEnumerable<Customer> GetAll()
        {
            return Customers;
        }

Plusieurs options sont offertes à vous pour modifier l'interface de SwaggerUI afin qu'elle corresponde, par exemple, à la charte graphique de votre entreprise ou de vos applications. Vous pouvez notamment :

• injecter des feuilles de style CSS ;
• injecter du code JavaScript ;
• ou encore, définir votre propre page index.

XII-A. Utiliser vos scripts personnalisés pour customiser l'interface de SwaggerUI▲

Nous allons apporter quelques modifications à l'interface de SwaggerUI en utilisant notre propre fichier CSS. Pour ce faire, nous allons dans un premier temps créer un dossier wwwroot à la racine de notre application, ensuite créer dans celui-ci un dossier swagger-ui, puis un dossier css dans le dossier swagger-ui. Dans le dossier css, nous allons créer le fichier custom.css, avec le contenu suivant :

 

Sélectionnez

.swagger-section #header {
    border-bottom: 1px solid #000000;
    font-style: normal;
    font-weight: 400;
    background-color: cornflowerblue;
}
.swagger-section #select_document {
     background: blueviolet;
}
.logo__title {
    display: none;
}

Pour que le contenu statique (CSS, image, JavaScript, HTML, etc.) soit rendu dans nos pages Web, nous devons configurer notre application pour prendre en charge cela. Pour ce faire, nous devons modifier la méthode Configure() du fichier Startup.cs pour ajouter le middleware permettant le support des fichiers statistiques :

 

Sélectionnez

     app.UseStaticFiles();

Si vous utilisez une version inférieure à ASP.NET Core 2.0, vous devez installer le package Microsoft.AspNetCore.StaticFiles.

Une fois cela fait, nous allons injecter le fichier CSS, en référençant son chemin relatif dans les options, lors de la configuration du middleware pour SwaggerUI :

 

Sélectionnez

app.UseSwaggerUI(c =>
             {
               c.SwaggerEndpoint("/swagger/v1/swagger.json", "SwaggerDemo v1");
                c.SwaggerEndpoint("/swagger/v2/swagger.json", "SwaggerDemo v2");
 
                 c.InjectStylesheet("/swagger-ui/css/custom.css");
             });

Une fois l'application en cours d'exécution, en accédant à la page de SwaggerUI, vous allez remarquer que la couleur du bandeau d'entête, ainsi que la couleur de la liste déroulante de sélection de la version de l'API ont changé :

Swagger est un outil puissant et populaire pour la génération de la documentation des Web API ASP.NET Core. En ayant recours à un tel outil, vous pouvez vous concentrer sur le développement de votre API, en éliminant les efforts qu'auraient demandés la production et la maintenance d'une documentation.

Ce tutoriel vous a permis de découvrir comment exploiter Swagger dans une Web API ASP.NET Core. J'espère qu'il vous aidera dans la prise en main du Framework.

Vous pouvez télécharger le code d'exemple sur ma page GitHub : https://github.com/hinault/SwaggerDemohttps://github.com/hinault/SwaggerDemo

Je tiens à remercier f-leb pour sa relecture orthographique.

Le GitHub du projet Swagger ;

Le GitHub du projet Swashbuckle.AspNetCore ;

Get started with Swashbuckle and ASP.NET Core ;

Swagger Editor.