Prise en charge d’OpenAPI dans les applications API minimales

La spécification OpenAPI est une norme indépendante du langage de programmation pour documenter les API HTTP. Dans cet article, nous allons découvrir comment OpenAPI est pris en charge dans les applications API minimales en utilisant une combinaison d’API intégrées et de bibliothèques open source.

Table des matières

Génération d’informations sur les points de terminaison

Les API minimales fournissent une prise en charge intégrée de la génération d’informations sur les points de terminaison dans une application grâce au package Microsoft.AspNetCore.OpenApi. Cela permet d’obtenir des informations précieuses sur les différentes URL de l’API.

Collecte des informations

La collecte des informations se fait dans un format qui correspond au schéma OpenAPI. Cela permet de structurer et de représenter les données de manière cohérente.

Exposition du schéma OpenAPI

Une fois le schéma OpenAPI généré, il peut être exposé via une interface utilisateur visuelle ou un fichier sérialisé. Cela permet aux développeurs et aux utilisateurs de l’API de comprendre facilement sa structure et son fonctionnement.

Le code suivant est un exemple d’application API minimale ASP.NET Core qui utilise OpenAPI :

using Microsoft.AspNetCore.OpenApi;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
var app = builder.Build();

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

app.UseHttpsRedirection();

var summaries = new[] { "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching" };

app.MapGet("/weatherforecast", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast(
            DateTime.Now.AddDays(index),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();

    return forecast;
})
.WithName("GetWeatherForecast")
.WithOpenApi();

app.Run();

internal record WeatherForecast(DateTime Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

Dans cet exemple de code, nous utilisons le package Microsoft.AspNetCore.OpenApi pour interagir avec les spécifications OpenAPI. Ce package joue un rôle essentiel en tant que lien entre les modèles OpenAPI et les points de terminaison des API minimales. Il fournit également une API permettant de construire des annotations OpenAPI pour décrire les points de terminaison.

package NuGet Microsoft.AspNetCore.OpenApi

ASP.NET Core fournit le package Microsoft.AspNetCore.OpenApi pour interagir avec les spécifications OpenAPI des points de terminaison. Ce package agit comme un lien entre les modèles OpenAPI définis dans Microsoft.AspNetCore.OpenApi et les points de terminaison des API minimales. Il permet d’examiner les paramètres, les réponses et les métadonnées d’un point de terminaison afin de construire une annotation OpenAPI correspondante.

Ajouter des annotations OpenAPI aux points de terminaison via WithOpenApi

L’appel à la méthode WithOpenApi sur un point de terminaison permet d’ajouter des métadonnées spécifiques à ce point de terminaison. Ces métadonnées peuvent être consommées par des packages tiers tels que Swashbuckle.AspNetCore ou affichées dans l’interface utilisateur Swagger générée pour décrire l’API.

Par exemple, pour ajouter une description au premier paramètre d’un point de terminaison, vous pouvez utiliser la méthode WithOpenApi avec une fonction comme suit :

app.MapPost("/todo2/{id}", async (int id, Todo todo, TodoDb db) =>
{
    todo.Id = id;
    db.Todos.Add(todo);
    await db.SaveChangesAsync();
    return Results.Created($"/todoitems/{todo.Id}", todo);
})
.WithOpenApi(generatedOperation =>
{
    var parameter = generatedOperation.Parameters[0];
    parameter.Description = "The ID associated with the created Todo";
    return generatedOperation;
});

Dans cet exemple, nous ajoutons une description au premier paramètre du point de terminaison en modifiant l’annotation OpenAPI générée.

Conclusion

La prise en charge d’OpenAPI dans les applications API minimales est une fonctionnalité puissante qui facilite la documentation et la compréhension des API. En utilisant les API intégrées et les bibliothèques open source telles que Microsoft.AspNetCore.OpenApi, il est possible de générer automatiquement des informations détaillées sur les points de terminaison et de les exposer via une interface utilisateur conviviale. Que vous soyez un développeur ou un utilisateur d’API, OpenAPI est un outil précieux pour comprendre et exploiter les API efficacement.

GUIDE