Prise en charge d’OpenAPI dans les applications API ASP.NET Core

ASP.NET Core prend en charge la génération de documents OpenAPI dans les applications API minimales et basées sur un contrôleur. La spécification OpenAPI est une norme indépendante du langage de programmation pour documenter les API HTTP. Cette norme est prise en charge dans les applications ASP.NET Core par le biais d’une combinaison d’API intégrées et de bibliothèques open source. L’intégration d’OpenAPI dans une application comporte trois aspects clés :

• Génération d’informations sur les points de terminaison dans l’application.
• Collecte des informations dans un format qui correspond au schéma OpenAPI.
• Exposition du document OpenAPI généré via une interface utilisateur visuelle ou un fichier sérialisé.

Les applications ASP.NET Core 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.

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.AddOpenApi();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

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

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 :

• AddOpenApi inscrit les services nécessaires à la génération de documents OpenAPI dans le conteneur DI de l’application.
• MapOpenApi ajoute un point de terminaison dans l’application pour afficher le document OpenAPI sérialisé en JSON. Le point de terminaison OpenAPI est limité à l’environnement de développement pour réduire le risque d’exposer des informations sensibles et réduire les vulnérabilités en production.

package NuGet Microsoft.AspNetCore.OpenApi

Le package Microsoft.AspNetCore.OpenApi 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é

Pour utiliser le package Microsoft.AspNetCore.OpenApi, ajoutez-le en tant que PackageReference à un fichier projet :

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

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

  <PropertyGroup>
    <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
    <OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)</OpenApiDocumentsDirectory>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.*-*" />
    <PackageReference Include="Microsoft.Extensions.ApiDescription.Server" Version="9.0.*-*">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
  </ItemGroup>

</Project>

Pour en savoir plus sur le package Microsoft.AspNetCore.OpenApi, consultez Générer des documents OpenAPI.

package NuGet Microsoft.Extensions.ApiDescription.Server

Le package Microsoft.Extensions.ApiDescription.Server prend en charge la génération de documents OpenAPI au moment de la génération et de leur sérialisation.

Pour utiliser Microsoft.Extensions.ApiDescription.Server, ajoutez-le en tant que PackageReference à un fichier projet. Pour activer la génération de documents au moment de la génération, définissez la propriété OpenApiGenerateDocuments. Par défaut, le document OpenAPI généré est enregistré dans le répertoire obj, mais vous pouvez personnaliser le répertoire de sortie en définissant la propriété OpenApiDocumentsDirectory.

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

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

  <PropertyGroup>
    <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
    <OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)</OpenApiDocumentsDirectory>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.*-*" />
    <PackageReference Include="Microsoft.Extensions.ApiDescription.Server" Version="9.0.*-*">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
  </ItemGroup>

</Project>

Code source OpenAPI d’ASP.NET Core sur GitHub

• AddOpenApi
• OpenApiDocumentService
• OpenApiOptions

Ressources complémentaires

• Authentification et autorisation dans les API minimales

La spécification OpenAPI est une norme indépendante du langage de programmation pour documenter les API HTTP. Cette norme est prise en charge dans les API minimales par le biais d’une combinaison d’API intégrées et de bibliothèques open source. L’intégration d’OpenAPI dans une application comporte trois aspects clés :

• Génération d’informations sur les points de terminaison dans l’application.
• Collecte des informations dans un format qui correspond au schéma OpenAPI.
• Exposition du schéma OpenAPI généré via une interface utilisateur visuelle ou un fichier sérialisé.

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.