Générer des documents OpenAPI

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 :

Visual Studio

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

Install-Package Microsoft.AspNetCore.OpenApi

CLI .NET

Exécutez la commande suivante :

dotnet add 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 :

Visual Studio

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

Install-Package Microsoft.Extensions.ApiDescription.Server

CLI .NET

Exécutez la commande suivante dans le répertoire contenant le fichier projet :

dotnet add 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();
}