Partager via

Générer des documents OpenAPI

  • Article

Le package Microsoft.AspNetCore.OpenApi fournit une prise en charge intégrée de la génération de documents OpenAPI dans ASP.NET Core. Le package offre les fonctionnalités suivantes :

  • Prise en charge de la génération de documents OpenAPI au moment de l’exécution et de leur accès via un point de terminaison au niveau de l’application
  • Prise en charge des API de type « transformateur » qui permettent de modifier le document généré
  • Prise en charge de la génération de plusieurs documents OpenAPI à partir d’une seule application
  • Tire parti de la prise en charge du schéma JSON fournie par System.Text.Json.
  • Est compatible avec AoT natif.

Installation de package

Installez le package Microsoft.AspNetCore.OpenApi :

Exécutez la commande suivante à partir de la console Gestionnaire de package:

Install-Package Microsoft.AspNetCore.OpenApi

Configurer la génération de document OpenAPI

Le code suivant :

  • Ajoute des services OpenAPI.
  • Active le point de terminaison pour afficher le document OpenAPI au format JSON.
var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi();

app.MapGet("/", () => "Hello world!");

app.Run();

Lancez l’application et accédez à https://localhost:<port>/openapi/v1.json pour afficher le document OpenAPI généré.

Options pour personnaliser la génération de document OpenAPI

Les sections suivantes montrent comment personnaliser la génération de document OpenAPI.

Personnaliser le nom du document OpenAPI

Chaque document OpenAPI dans une application a un nom unique. Le nom du document par défaut inscrit est v1.

builder.Services.AddOpenApi(); // Document name is v1

Le nom du document peut être modifié en passant le nom en tant que paramètre à l’appel AddOpenApi.

builder.Services.AddOpenApi("internal"); // Document name is internal

Le nom du document s’affiche à plusieurs endroits dans l’implémentation OpenAPI.

Lors de l’extraction du document OpenAPI généré, le nom du document est fourni en tant qu’argument de paramètre documentName dans la requête. Les requêtes suivantes résolvent les documents v1 et internal.

GET http://localhost:5000/openapi/v1.json
GET http://localhost:5000/openapi/internal.json

Personnaliser la version OpenAPI d’un document généré

Par défaut, la génération de document OpenAPI crée un document conforme à la version 3.0 de la spécification OpenAPI. Le code suivant montre comment modifier la version par défaut du document OpenAPI :

builder.Services.AddOpenApi(options =>
{
    options.OpenApiVersion = OpenApiSpecVersion.OpenApi2_0;
});

Personnaliser l’itinéraire du point de terminaison OpenAPI

Par défaut, le point de terminaison OpenAPI inscrit via un appel à MapOpenApi expose le document au niveau du point de terminaison /openapi/{documentName}.json. Le code suivant montre comment personnaliser l’itinéraire au niveau duquel le document OpenAPI est inscrit :

app.MapOpenApi("/openapi/{documentName}/openapi.json");

Bien que ce ne soit pas recommandé, il est possible de supprimer le paramètre de routage documentName de l’itinéraire du point de terminaison. Lorsque le paramètre d’itinéraire documentName est supprimé de l’itinéraire du point de terminaison, l’infrastructure tente de résoudre le nom du document à partir du paramètre de requête. Ne pas fournir le documentName dans l’itinéraire ou la requête peut entraîner un comportement inattendu.

Personnaliser le point de terminaison OpenAPI

Étant donné que le document OpenAPI est fourni via un point de terminaison de gestionnaire de routage, toute personnalisation disponible pour les points de terminaison minimaux standard l’est aussi pour le point de terminaison OpenAPI.

Limiter l’accès au document OpenAPI aux utilisateurs autorisés

Par défaut, le point de terminaison OpenAPI n’active aucune vérification des autorisations. Toutefois, des vérifications d’autorisation peuvent être appliquées au document OpenAPI. Dans le code suivant, l’accès au document OpenAPI est limité aux utilisateurs disposant du rôle tester :

using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder();

builder.Services.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorization(o =>
{
    o.AddPolicy("ApiTesterPolicy", b => b.RequireRole("tester"));
});
builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi()
    .RequireAuthorization("ApiTesterPolicy");

app.MapGet("/", () => "Hello world!");

app.Run();

Mettre en cache le document OpenAPI généré

Le document OpenAPI est régénéré chaque fois qu’une requête est envoyée au point de terminaison OpenAPI. La régénération permet aux transformateurs d’incorporer l’état de l’application dynamique dans leur fonctionnement. Par exemple,vous pouvez régénérer une requête avec les détails du contexte HTTP. Le cas échéant, le document OpenAPI peut être mis en cache pour éviter d’exécuter le pipeline de génération de documents sur chaque requête HTTP.

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder();

builder.Services.AddOutputCache(options =>
{
    options.AddBasePolicy(policy => policy.Expire(TimeSpan.FromMinutes(10)));
});
builder.Services.AddOpenApi();

var app = builder.Build();

app.UseOutputCache();

app.MapOpenApi()
    .CacheOutput();

app.MapGet("/", () => "Hello world!");

app.Run();

Générer des documents OpenAPI au moment de la génération

Dans les applications web classiques, les documents OpenAPI sont générés au moment de l’exécution et servis via une requête HTTP au serveur d’applications.

Dans certains scénarios, il est utile de générer le document OpenAPI pendant l’étape de génération de l’application. Ces scénarios sont les suivants :

  • Génération de la documentation OpenAPI validée dans le contrôle de code source.
  • Génération de la documentation OpenAPI utilisée pour les tests d’intégration basés sur des spécifications.
  • Génération de la documentation OpenAPI qui est servie statiquement à partir du serveur web.

Pour ajouter la prise en charge de la génération de documents OpenAPI au moment de la génération, installez le package Microsoft.Extensions.ApiDescription.Server :

Exécutez la commande suivante à partir de la console Gestionnaire de package:

Install-Package Microsoft.Extensions.ApiDescription.Server

Lors de l’installation, ce package génère automatiquement le ou les documents Open API associés à l’application pendant la génération et les remplit dans le répertoire de sortie de l’application.

$ dotnet build
$ cat bin/Debug/net9.0/{ProjectName}.json

Personnalisation de la génération de documents au moment de la génération

Modification du répertoire de sortie du fichier OPEN API généré

Par défaut, le document OpenAPI généré est émis dans le répertoire de sortie de l’application. Pour modifier l’emplacement du fichier émis, définissez le chemin d’accès cible dans la OpenApiDocumentsDirectory propriété.

<PropertyGroup>
  <OpenApiDocumentsDirectory>./</OpenApiDocumentsDirectory>
</PropertyGroup>

La valeur de OpenApiDocumentsDirectory est résolue par rapport au fichier projet. L’utilisation de la ./ valeur ci-dessus émet le document OpenAPI dans le même répertoire que le fichier projet.

Modification du nom du fichier de sortie

Par défaut, le document OpenAPI généré aura le même nom que le fichier projet de l’application. Pour modifier le nom du fichier émis, définissez l’argument --file-name dans la OpenApiGenerateDocumentsOptions propriété.

<PropertyGroup>
  <OpenApiGenerateDocumentsOptions>--file-name my-open-api</OpenApiGenerateDocumentsOptions>
</PropertyGroup>

Sélection du document OpenAPI à générer

Certaines applications peuvent être configurées pour émettre plusieurs documents OpenAPI, pour différentes versions d’une API ou pour faire la distinction entre les API publiques et internes. Par défaut, le générateur de documents au moment de la génération émet des fichiers pour tous les documents configurés dans une application. Pour émettre uniquement un nom de document unique, définissez l’argument --document-name dans la OpenApiGenerateDocumentsOptions propriété.

<PropertyGroup>
  <OpenApiGenerateDocumentsOptions>--document-name v2</OpenApiGenerateDocumentsOptions>
</PropertyGroup>

Personnalisation du comportement d’exécution pendant la génération du document au moment de la génération du document au moment de la génération

Sous le capot, les fonctions de génération de documents OpenAPI au moment de la génération en lançant le point d’entrée de l’application avec une implémentation de serveur inerte. Il s’agit d’une exigence de produire des documents OpenAPI précis, car toutes les informations contenues dans le document OpenAPI ne peuvent pas être analysées de manière statique. Étant donné que le point d’entrée de l’application est appelé, toute logique au démarrage des applications est appelée. Cela inclut le code qui injecte des services dans le conteneur d’adresses diiques ou lit à partir de la configuration. Dans certains scénarios, il est nécessaire de restreindre les chemins de code qui s’exécutent lorsque le point d’entrée de l’application est appelé à partir de la génération de document au moment de la génération du document au moment de la génération. Ces scénarios sont les suivants :

  • Impossible de lire à partir de certaines chaînes de configuration.
  • Ne pas inscrire les services liés à la base de données.

Pour empêcher ces chemins de code d’être appelés par le pipeline de génération au moment de la génération de build, ils peuvent être conditionnés derrière une vérification de l’assembly d’entrée comme suit :

using System.Reflection;

var builder = WebApplication.CreateBuilder();

if (Assembly.GetEntryAssembly()?.GetName().Name != "GetDocument.Insider")
{
  builder.Services.AddDefaults();
}

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 via le package Microsoft.AspNetCore.OpenApi. L’exposition de la définition OpenAPI générée via une interface utilisateur visuelle nécessite un package tiers. Pour plus d’informations sur la prise en charge d’OpenAPI dans les API basées sur un contrôleur, consultez la version .NET 9 de cet article.

Le code suivant est généré par le modèle d’API web minimal ASP.NET Core et 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 le code en surbrillance précédent :

  • Microsoft.AspNetCore.OpenApi est expliqué dans la section suivante.
  • AddEndpointsApiExplorer : configure l’application afin d’utiliser l’API Explorer pour découvrir et décrire des points de terminaison avec des annotations par défaut. WithOpenApi remplace la correspondance, les annotations par défaut générées par l’API Explorer avec celles produites à partir du package Microsoft.AspNetCore.OpenApi.
  • UseSwagger ajoute l’intergiciel Swagger.
  • `UseSwaggerUI` active une version incorporée de l’outil de l’interface utilisateur Swagger.
  • WithName : le IEndpointNameMetadata sur le point de terminaison est utilisé pour la génération de liens et est traité comme l’ID d’opération dans la spécification OpenAPI du point de terminaison donné.
  • WithOpenApi est expliqué plus loin dans cet article.

package NuGet Microsoft.AspNetCore.OpenApi

ASP.NET Core fournit le package Microsoft.AspNetCore.OpenApi pour interagir avec les spécifications OpenAPI pour les points de terminaison. Le package agit comme un lien entre les modèles OpenAPI définis dans le package Microsoft.AspNetCore.OpenApi et les points de terminaison définis dans les API minimales. Le package fournit une API qui examine les paramètres, les réponses et les métadonnées d’un point de terminaison pour construire un type d’annotation OpenAPI utilisé pour décrire un point de terminaison.

Microsoft.AspNetCore.OpenApi est ajouté en tant que PackageReference à un fichier projet :

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net7.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>    
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="7.0.*-*" />
    <PackageReference Include="Swashbuckle.AspNetCore" Version="6.4.0" />
  </ItemGroup>

</Project>

Lors de l’utilisation de Swashbuckle.AspNetCore avec Microsoft.AspNetCore.OpenApi, Swashbuckle.AspNetCore version 6.4.0 ou ultérieure doit être utilisée. Microsoft.OpenApi version 1.4.3 ou ultérieure doit être utilisée pour tirer parti des constructeurs de copie dans les appels WithOpenApi.

Ajouter des annotations OpenAPI aux points de terminaison via WithOpenApi

Appeler WithOpenApi sur le point de terminaison permet l’ajout aux métadonnées du point de terminaison. Ces métadonnées peuvent être :

  • Consommées dans des packages tiers comme Swashbuckle.AspNetCore.
  • Affichées dans l’interface utilisateur Swagger ou en YAML ou JSON généré pour définir l’API.
app.MapPost("/todoitems/{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();

Modifier l’annotation OpenAPI dans WithOpenApi

La méthode WithOpenApi accepte une fonction qui peut être utilisée pour modifier l’annotation OpenAPI. Par exemple, dans le code suivant, une description est ajoutée au premier paramètre du point de terminaison :

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;
});

Ajouter des ID d’opération à OpenAPI

Les ID d’opération sont utilisés pour identifier de manière unique un point de terminaison donné dans OpenAPI. Il est possible d’utiliser la méthode d’extension WithName pour définir l’ID d’opération utilisé pour une méthode.

app.MapGet("/todoitems2", async (TodoDb db) =>
    await db.Todos.ToListAsync())
    .WithName("GetToDoItems");

Vous pouvez également définir la propriété OperationId directement sur l’annotation OpenAPI.

app.MapGet("/todos", async (TodoDb db) => await db.Todos.ToListAsync())
    .WithOpenApi(operation => new(operation)
    {
        OperationId = "GetTodos"
    });

Ajouter des balises à la description OpenAPI

OpenAPI prend en charge l’utilisation d’objets de balise pour catégoriser les opérations. Ces balises sont généralement utilisées pour regrouper des opérations dans l’interface utilisateur de Swagger. Ces balises peuvent être ajoutées à une opération en appelant la méthode d’extension WithTags sur le point de terminaison avec les balises souhaitées.

app.MapGet("/todoitems", async (TodoDb db) =>
    await db.Todos.ToListAsync())
    .WithTags("TodoGroup");

Vous pouvez également définir la liste de OpenApiTags sur l’annotation OpenAPI via la méthode d’extension WithOpenApi .

app.MapGet("/todos", async (TodoDb db) => await db.Todos.ToListAsync())
    .WithOpenApi(operation => new(operation)
    {
        Tags = new List<OpenApiTag> { new() { Name = "Todos" } }
    });

Ajouter un résumé ou une description du point de terminaison

Le résumé et la description du point de terminaison peuvent être ajoutés en appelant la méthode d’extension WithOpenApi. Dans le code suivant, les résumés sont définis directement sur l’annotation OpenAPI.

app.MapGet("/todoitems2", async (TodoDb db) => await db.Todos.ToListAsync())
    .WithOpenApi(operation => new(operation)
    {
        Summary = "This is a summary",
        Description = "This is a description"
    });

Exclure la description OpenAPI

Dans l’exemple suivant, le point de terminaison /skipme est exclu et ne peut pas générer une description 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();

app.MapGet("/swag", () => "Hello Swagger!")
    .WithOpenApi();
app.MapGet("/skipme", () => "Skipping Swagger.")
                    .ExcludeFromDescription();

app.Run();

Marquer une API comme obsolète

Pour marquer un point de terminaison comme obsolète, définissez la propriété Deprecated sur l’annotation OpenAPI.

app.MapGet("/todos", async (TodoDb db) => await db.Todos.ToListAsync())
    .WithOpenApi(operation => new(operation)
    {
        Deprecated = true
    });

Décrire des types de réponse

OpenAPI prend en charge la description des réponses retournées par une API. Les API minimales prennent en charge trois stratégies pour définir le type de réponse d’un point de terminaison :

  • Via la méthode d’extension Produces sur le point de terminaison
  • Via l’attribut ProducesResponseType sur le gestionnaire de routage
  • En retournant TypedResults à partir du gestionnaire de routage

Il est possible d’utiliser la méthode d’extension Produces pour ajouter des métadonnées Produces à un point de terminaison. Quand aucun paramètre n’est fourni, la méthode d’extension remplit les métadonnées pour le type ciblé sous un code d’état 200 et un type de contenu application/json.

app
    .MapGet("/todos", async (TodoDb db) => await db.Todos.ToListAsync())
    .Produces<IList<Todo>>();

L’utilisation de TypedResults dans l’implémentation du gestionnaire de routage d’un point de terminaison inclut automatiquement les métadonnées du type de réponse pour le point de terminaison. Par exemple, le code suivant annote automatiquement le point de terminaison avec une réponse sous le code d’état 200 avec un type de contenu application/json.

app.MapGet("/todos", async (TodoDb db) =>
{
    var todos = await db.Todos.ToListAsync());
    return TypedResults.Ok(todos);
});

Définir des réponses pour ProblemDetails

Lors de la définition du type de réponse pour les points de terminaison susceptibles de renvoyer une réponse ProblemDetails, les méthodes d’extension ProducesProblem ou ProducesValidationProblem ou TypedResults.Problem peuvent être utilisées pour ajouter l’annotation appropriée aux métadonnées du point de terminaison. Notez que les méthodes d’extension ProducesProblem et ProducesValidationProblem ne peuvent pas être utilisées avec des groupes de gammes dans .NET 8 et versions antérieures .

Lorsqu’aucune annotation explicite n’est fournie par l’une des stratégies ci-dessus, l’infrastructure tente de déterminer un type de réponse par défaut en examinant la signature de la réponse. Cette réponse par défaut est remplie sous le code d’état 200 dans la définition OpenAPI.

Types de réponse multiples

Si un point de terminaison peut retourner différents types de réponse dans différents scénarios, vous pouvez fournir des métadonnées des manières suivantes :

  • Appeler la méthode d’extension Produces plusieurs fois, comme illustré dans l’exemple suivant :

    app.MapGet("/api/todoitems/{id}", async (int id, TodoDb db) =>
         await db.Todos.FindAsync(id) 
         is Todo todo
         ? Results.Ok(todo) 
         : Results.NotFound())
   .Produces<Todo>(StatusCodes.Status200OK)
   .Produces(StatusCodes.Status404NotFound);

  • Utiliser Results<TResult1,TResult2,TResultN> dans la signature et TypedResults dans le corps du gestionnaire, comme illustré dans l’exemple suivant :

    app.MapGet("/book/{id}", Results<Ok<Book>, NotFound> (int id, List<Book> bookList) =>
{
    return bookList.FirstOrDefault((i) => i.Id == id) is Book book
     ? TypedResults.Ok(book)
     : TypedResults.NotFound();
});

    Les Results<TResult1,TResult2,TResultN> types d’union déclarent qu’un gestionnaire de routage retourne plusieurs types concrets implémentant IResult, et tous les types qui implémentent IEndpointMetadataProvider contribueront aux métadonnées du point de terminaison.

    Les types d’union implémentent des opérateurs de cast implicites. Ces opérateurs permettent au compilateur de convertir automatiquement les types spécifiés dans les arguments génériques en instance du type union. Cette fonctionnalité présente l’avantage supplémentaire de vérifier au moment de la compilation qu’un gestionnaire de routage retourne uniquement les résultats qu’il déclare faire. La tentative de retourner un type qui n’est pas déclaré comme l’un des arguments génériques vers Results<TResult1,TResult2,TResultN> entraîne une erreur de compilation.

Décrire le corps et les paramètres de la requête

En plus de décrire les types retournés par un point de terminaison, OpenAPI prend également en charge l’annotation des entrées consommées par une API. Ces entrées se répartissent en deux catégories :

  • Paramètres qui apparaissent dans le chemin d’accès, la chaîne de requête, les en-têtes ou les cookies
  • Données transmises dans le corps de la requête

L’infrastructure déduit automatiquement les types des paramètres de requête dans le chemin d’accès, la requête et la chaîne d’en-tête en fonction de la signature du gestionnaire de routage.

Pour définir le type d’entrées transmises en tant que corps de la demande, configurez les propriétés à l’aide de la méthode d’extension Accepts pour définir le type d’objet et le type de contenu attendus par le gestionnaire de requêtes. Dans l’exemple suivant, le point de terminaison accepte un objet Todo dans le corps de la requête avec un type de contenu attendu de application/xml.

app.MapPost("/todos/{id}", (int id, Todo todo) => ...)
  .Accepts<Todo>("application/xml");

En plus de la méthode d’extension Accepts, un type de paramètre peut décrire sa propre annotation en implémentant l’interface IEndpointParameterMetadataProvider. Par exemple, le type Todo suivant ajoute une annotation qui nécessite un corps de requête avec un type de contenu application/xml.

public class Todo : IEndpointParameterMetadataProvider
{
    public static void PopulateMetadata(ParameterInfo parameter, EndpointBuilder builder)
    {
        builder.Metadata.Add(new ConsumesAttribute(typeof(Todo), isOptional: false, "application/xml"));
    }
}

Lorsqu’aucune annotation explicite n’est fournie, l’infrastructure tente de déterminer le type de requête par défaut s’il existe un paramètre de corps de la demande dans le gestionnaire de point de terminaison. L’inférence utilise l’heuristique suivante pour produire l’annotation :

  • Les paramètres du corps de la requête qui sont lus à partir d’un formulaire via l’attribut [FromForm] sont décrits avec le type de contenu multipart/form-data.
  • Tous les autres paramètres du corps de la requête sont décrits avec le type de contenu application/json.
  • Le corps de la requête est traité comme facultatif s’il peut avoir la valeur Null ou si la propriété AllowEmpty est définie sur l’attribut FromBody.

Contrôle de version de l’API de support

Les API minimales prennent en charge le contrôle de version des API via le package Asp.Versioning.Http. Vous trouverez des exemples de configuration du contrôle de version avec des API minimales dans le référentiel de gestion des versions d’API.

Code source OpenAPI d’ASP.NET Core sur GitHub

Ressources complémentaires

Une application API minimale peut décrire la spécification OpenAPI pour les gestionnaires de routage à l’aide de Swashbuckle.

Pour plus d’informations sur la prise en charge d’OpenAPI dans les API basées sur un contrôleur, consultez la version .NET 9 de cet article.

Le code suivant est une application ASP.NET Core classique avec prise en charge d’OpenAPI :

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new() { Title = builder.Environment.ApplicationName,
                               Version = "v1" });
});

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger(); // UseSwaggerUI Protected by if (env.IsDevelopment())
    app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json",
                                    $"{builder.Environment.ApplicationName} v1"));
}

app.MapGet("/swag", () => "Hello Swagger!");

app.Run();

Exclure la description OpenAPI

Dans l’exemple suivant, le point de terminaison /skipme est exclu et ne peut pas générer une description OpenAPI :

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI(); // UseSwaggerUI Protected by if (env.IsDevelopment())
}

app.MapGet("/swag", () => "Hello Swagger!");
app.MapGet("/skipme", () => "Skipping Swagger.")
                    .ExcludeFromDescription();

app.Run();

Décrire des types de réponse

L’exemple suivant utilise les types de résultats intégrés pour personnaliser la réponse :

app.MapGet("/api/todoitems/{id}", async (int id, TodoDb db) =>
         await db.Todos.FindAsync(id) 
         is Todo todo
         ? Results.Ok(todo) 
         : Results.NotFound())
   .Produces<Todo>(StatusCodes.Status200OK)
   .Produces(StatusCodes.Status404NotFound);

Ajouter des ID d’opération à OpenAPI

app.MapGet("/todoitems2", async (TodoDb db) =>
    await db.Todos.ToListAsync())
    .WithName("GetToDoItems");

Ajouter des balises à la description OpenAPI

Le code suivant utilise une balise de regroupement OpenAPI :

app.MapGet("/todoitems", async (TodoDb db) =>
    await db.Todos.ToListAsync())
    .WithTags("TodoGroup");