Documentation Swagger avec des bibliothèques externes

Utiliser plusieurs bibliothèques pour diviser votre code pour des cas futurs est une bonne chose. Personnellement, j’adore le faire, si je peux diviser ma logique pour qu’elle puisse être réutilisée dans d’autres projets ou parties de projets.

Pour moi au moins, il est indispensable de diviser les modèles de données, qui incluent le Entity Framework, afin qu’il puisse être référencé et utilisé dans un Console application, un Blazor application ou un API.

Jetons un coup d’œil à un exemple de la façon dont je fais les choses, il s’agit d’une capture d’écran d’un projet comportant quelques applications et une bibliothèque partagée contenant tous les modèles.

Ceci est un exemple de classe que j’ai déplacée du projet API avec une documentation avec summary sur chaque propriété et classe.

namespace CustomLibrariesDocumentation.Models
{
    /// <summary>
    /// WeatherForecast class
    /// </summary>
    public class WeatherForecast
    {
        /// <summary>
        /// Gets or sets the Date
        /// </summary>
        public DateOnly Date { get; set; }

        /// <summary>
        /// Gets or sets the TemperatureC
        /// </summary>
        public int TemperatureC { get; set; }

        /// <summary>
        /// Gets or sets the TemperatureF
        /// </summary>
        public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);

        /// <summary>
        /// Gets or sets the Summary
        /// </summary>
        public string? Summary { get; set; }
    }
}

Si nous le référençons au Console application et que nous commençons à utiliser le modèle, nous pouvons voir la documentation, c’est une fonctionnalité standard dans Visual Studio donc cela fonctionne bien, comme vous pouvez le voir ici :

Mais ensuite, si nous le référençons au API et que nous passons à Swagger, il n’y a pas de documentation récapitulative.

Comment pouvons-nous résoudre ce problème ?

Tout d’abord, nous devons activer les commentaires XML sur la bibliothèque, pour ce faire, vous devez mettre à jour les paramètres du projet et activer `` :

Cela générera des fichiers sur le dossier de construction qui se terminent par l’extension de fichier xml, comme vous pouvez le voir ici :

Maintenant que nous avons fait cela, nous devons ajouter quelques éléments sur le Program.cs, afin de pouvoir lire ces fichiers, car par défaut, il ne charge que la définition XML du projet sur lequel il se trouve.

Il utilise une méthode que nous avons à l’intérieur du AddSwaggerGen et qui s’appelle IncludeXmlComments.

L’idée est que si nous avons tous les fichiers xml, nous allons forcer leur chargement sur le Swagger.

builder.Services.AddSwaggerGen(s =>
{
    // Comments
    var allXmlFiles = Directory.GetFiles(AppContext.BaseDirectory, "*.xml");

    foreach (string xmlFiles in allXmlFiles)
    {
        s.IncludeXmlComments(xmlFiles);
    }
});

C’est simple, nous récupérons les fichiers xml du répertoire de construction et les ajoutons avec la méthode IncludeXmlComments .

Maintenant, nous chargeons à nouveau le API et nous vérifions si nous pouvons voir la documentation.

Et vous voyez qu’on peut voir la documentation !

J’espère que cela vous a aidé, si vous avez des questions, n’hésitez pas à me contacter !