Notions de base d’ASP.NET Core : documentation des API

Des API bien documentées sont essentielles à la réussite d’un projet web. Consultez cet article pour découvrir des ressources importantes pour documenter les API dans ASP.NET Core.

Les interfaces de programmation d’applications (API) permettent à deux composants logiciels de communiquer entre eux à l’aide d’un ensemble de définitions (authentification, données d’entrée et de sortie, etc.) et de protocoles (REST, SOAP, GraphQL, etc.), où un client fait une demande et un serveur répond avec un succès ou une erreur.

Bien qu’il soit possible d’utiliser une API avec peu ou pas de documentation, il est toujours recommandé que les informations pertinentes sur une API soient disponibles et facilement accessibles. Après tout, c’est grâce à la documentation que les développeurs peuvent découvrir les détails d’une nouvelle API, qui apporte souvent des fonctionnalités essentielles pour l’intégration avec d’autres systèmes.

Imaginez que vous visitez une ville où vous n’êtes jamais allé. Ne serait-il pas bien d’avoir une carte avec les principales attractions touristiques ? Vous pouvez trouver des lieux simplement en les recherchant, mais cela peut prendre beaucoup plus de temps que prévu. Imaginez que vous essayez de vous repérer dans la ville simplement en regardant les noms des rues et en interrogeant les résidents.

La documentation d’une API constitue une bonne carte pour les développeurs, fournissant des instructions claires sur la façon d’utiliser chaque fonctionnalité. Vous n’avez pas besoin de deviner, suivez simplement les instructions.

Dans cet article, nous explorerons les principales ressources disponibles pour travailler avec la documentation API dans ASP.NET Core, telles que les résumés et les fichiers XML. De plus, nous examinerons certains outils tiers tels que Swagger et Docfx.

Création de l’application et ajout de ressources de documentation

L’exemple d’application n’utilisera aucune base de données. Au lieu de cela, nous utiliserons ceux configurés précédemment pour démontrer les fonctionnalités décrites dans l’article.

Nous allons créer une API Web dans ASP.NET Core pour gérer les données d’événements. Lors du développement de l’application de base, nous explorerons les ressources de documentation et verrons quelles configurations et implémentations sont requises pour cela.

Vous pouvez vérifier le code source de l’application modèle sur ce lien : Code source d’EventMaster.

Conditions préalables

• .NET8 ou plus
• Visual Studio (certaines configurations seront réalisées à l’aide de Visual Studio, ce qui peut être réalisé d’une autre manière, mais celles-ci ne sont pas abordées dans cet article)

Ainsi, pour créer l’application de base, vous pouvez exécuter la commande ci-dessous ou, si vous préférez, vous pouvez utiliser Visual Studio et choisir le modèle d’API Web ASP.NET Core.

Créer une commande :

dotnet new webapi -n EventMaster

Le <summary> La balise est un bloc de commentaires utilisé pour fournir une description concise et significative de ce que fait un élément donné, généralement placé au-dessus de l’élément documenté. Visual Studio IntelliSense utilise des balises récapitulatives pour afficher des informations supplémentaires sur un type ou un membre.

Donc, pour créer les entités, créez d’abord un nouveau dossier appelé « Modèles » et à l’intérieur, créez la classe ci-dessous :

namespace EventMaster.Models;

public class Event
{
    
    
    
    public Guid Id { get; set; }

    
    
    
    public string Name { get; set; }

    
    
    
    public DateTime Date { get; set; }

    
    
    
    public string Location { get; set; }

    
    
    
    public List<string> Speakers { get; set; }
}

Notez que le résumé du nom de l’événement contient des informations pertinentes qui montrent des détails subtils.

Création du contrôleur

Créons maintenant le contrôleur pour rendre les points de terminaison de l’API disponibles.

Créez un nouveau dossier appelé « Contrôleurs » et à l’intérieur, créez le contrôleur ci-dessous :

using EventMaster.Models;
using Microsoft.AspNetCore.Mvc;

namespace EventMaster.Data
{
    
    
    
    [ApiController]
    [Route("api/event")]
    public class EventController : ControllerBase
    {
        private readonly List<Event> events = new List<Event>();

        public EventController()
        {
            events = GenerateSampleEvents();
        }

        
        
        
        
        [HttpGet]
        [ProducesResponseType(200, Type = typeof(IEnumerable<Event>))]
        public IActionResult GetAllEvents()
        {
            return Ok(events);
        }

        
        
        
        
        
        [HttpGet("{id}")]
        [ProducesResponseType(200, Type = typeof(Event))]
        [ProducesResponseType(404)]
        public IActionResult GetEventById(Guid id)
        {
            var entityById = events.SingleOrDefault(e => e.Id == id);
            return entityById != null ? Ok(entityById) : NotFound();
        }

        
        
        
        
        
        [HttpPost]
        [ProducesResponseType(201, Type = typeof(Event))]
        public IActionResult CreateEvent([FromBody] Event entity)
        {
            
            return Created("/api/event", entity);
        }

        
        
        
        
        
        
        [HttpPut("{id}")]
        [ProducesResponseType(204)]
        [ProducesResponseType(404)]
        public IActionResult UpdateEvent(int id, [FromBody] Event entity)
        {
            
            return NoContent();
        }

        
        
        
        
        
        [HttpDelete("{id}")]
        [ProducesResponseType(204)]
        [ProducesResponseType(404)]
        public IActionResult DeleteEvent(int id)
        {
            
            return NoContent();
        }

        private List<Event> GenerateSampleEvents()
        {
            return new List<Event>
            {
                new Event
                {
                    Id = new Guid("c730d19e-7d7a-4e36-b450-92b011b7a24f"),
                    Name = "Tech Summit 2024",
                    Date = new DateTime(2024, 3, 15, 9, 0, 0),
                    Location = "Convention Center, San Francisco",
                    Speakers = new List<string> { "John Smith", "Emily Johnson", "Michael Lee" }
                },
                new Event
                {
                    Id = new Guid("f88b2443-95e4-4a89-9fc8-82b922c59391"),
                    Name = "Startup Launchpad",
                    Date = new DateTime(2024, 5, 20, 10, 0, 0),
                    Location = "Tech Hub, New York",
                    Speakers = new List<string> { "Sarah Brown", "David Clark" }
                },
                new Event
                {
                    Id = new Guid("b9284822-0e46-4ae1-bc6e-37e53a2f4e13"),
                    Name = "Data Science Conference",
                    Date = new DateTime(2024, 8, 10, 8, 30, 0),
                    Location = "University Auditorium, Chicago",
                    Speakers = new List<string> { "Alex Rodriguez", "Rachel Green", "Chris Thompson" }
                }
            };
        }
    }
}

Notez que chaque point de terminaison dispose d’un résumé décrivant ce que fait chaque point de terminaison, en plus de spécifier le code HTTP renvoyé via le [ProducesResponseType(HTTP code)] annotation. Est également présent le <param name=""> balise, qui est utilisée pour spécifier les détails des paramètres d’entrée d’une méthode.

Si vous déclarez la propriété Nom de l’entité événementielle, vous pourrez voir la description configurée dans le résumé.

Configuration de la classe de programme

Configurons maintenant la classe Program et rendons l’API fonctionnelle. Remplacez donc le code existant dans la classe Program par le code ci-dessous :

using Microsoft.OpenApi.Models;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddControllers();

var app = builder.Build();

app.MapControllers();
app.UseHttpsRedirection();
app.Run();

Génération du fichier de documentation XML

Grâce à Visual Studio, il est possible de générer un fichier XML avec les détails de la documentation que nous avons rédigée dans le résumé. De plus, il apporte d’autres détails basés sur le code créé tels que les entités de modèle et de contrôleur.

Pour générer le fichier de documentation XML, nous devons d’abord le configurer via Visual Studio. Alors, suivez les étapes ci-dessous :

1. Faites un clic droit sur le projet.
2. Dans l’onglet qui s’ouvre, sélectionnez Propriétés.
3. Dans l’onglet de gauche, sélectionnez Créer.
4. Dans le sous-onglet, sélectionnez Sortie.
5. Dans le champ « Chemin du fichier de documentation XML », ajoutez le nom du fichier avec l’extension (dans ce cas, EventMasterSwaggerAnnotation.xml.

L’image ci-dessous montre le processus :

Désormais, lorsque l’application est en cours d’exécution, le fichier XML sera créé dans le répertoire racine de l’application.

Affichage de la documentation via une interface

Swagger est une alternative à l’affichage des détails de l’API précédemment configurés. Pour l’utiliser, vous devez installer les packages NuGet dans l’application.

dotnet add package Microsoft.AspNetCore.OpenApi
dotnet add package Swashbuckle.AspNetCore.Annotations

Et dans le Program.cs, ajoutez le code suivant :

builder.Services.AddSwaggerGen(
    c =>
    {
        c.EnableAnnotations();
        c.SwaggerDoc("v1", new OpenApiInfo
        {
            Title = "EventMaster Web API",
            Description = "API to manager events",
            Contact = new OpenApiContact() { Name = "John Smith", Email = "jsmith@mayl.com" },
            License = new OpenApiLicense() { Name = "MIT License", Url = new Uri("https://opensource.org/licenses/MIT") }
        });
        c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, "EventMasterSwaggerAnnotation.xml"));
    }
);

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

Si vous exécutez l’application, vous pouvez vérifier les fonctionnalités de Swagger.

Notez que tous les détails qui ont été configurés via les résumés sont reflétés dans l’interface Swagger, ce qui facilite la compréhension pour quiconque a besoin d’informations sur l’application, sans avoir à recourir au code source.

Générer de la documentation avec Docfx

Docfx est un générateur de documentation API pour .NET, qui prend en charge C# et vous permet de personnaliser la documentation en fonction de certains paramètres préconfigurés.

Grâce aux commandes du terminal, docFX crée un site Web HTML statique basé sur le code source référencé.

Pour générer de la documentation pour l’exemple de projet, dans le dossier où se trouve le projet créé, ouvrez un terminal et exécutez la commande ci-dessous pour installer les dépendances docfx :

dotnet tool update -g docfx

Remplissez ensuite les données demandées comme indiqué dans les images ci-dessous :

Maintenant, pour créer les documents, exécutez :

docfx docfx.json --serve

Si vous accédez http://localhost:8080vous pouvez voir l’interface docfx avec la documentation API nouvellement générée.

Conclusion

La documentation des API est essentielle pour maintenir la qualité d’un projet et accélérer le processus d’intégration entre les applications. Après tout, une bonne documentation est similaire à une carte qui fournit des informations pertinentes pour guider les nouveaux aventuriers.

Dans cet article, nous avons vu quelques ressources natives ASP.NET Core pour la documentation des API, telles que summary et le fichier XML généré par Visual Studio. De plus, nous avons vu des ressources tierces telles que Swagger, qui possède une interface interactive, et docfx qui fournit des pages HTML générées via des commandes de terminal.

L’apprentissage de la documentation est très important pour quiconque débute dans le développement de logiciels, car cela démontre que le développeur comprend l’importance d’enregistrer et d’expliquer le fonctionnement du code qu’il produit. De plus, la création d’une documentation claire et concise facilite la compréhension du fonctionnement d’une application et aide les autres développeurs à modifier le code.