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>

API v. Opération d’API v. Point de terminaison d’API

Les sections suivantes expliquent les différences entre une API, un point de terminaison d’API et une opération d’API dans le contexte de la documentation ASP.NET Core et OpenAPI.

API (Interface de programmation d’applications)

Une API est un ensemble de règles et de protocoles permettant de créer et d’interagir avec des applications logicielles. Il définit la façon dont différents composants logiciels doivent communiquer. En général, le développement web « API » fait généralement référence à un service web qui expose les fonctionnalités via HTTP.

Dans ASP.NET Core, une API est généralement générée à l’aide de contrôleurs ou d’API minimales, qui gèrent les requêtes HTTP entrantes et les réponses renvoyées.

ASP.NET Core utilise parfois les conventions internes de dénomination différemment pour « API ». Par exemple, dans l’Explorateur d’API, une « ApiDescription » représente en fait une opération d’API plutôt que le service d’API complet. Cette distinction reflète les conventions d’affectation de noms internes et diffère parfois de la définition plus large utilisée ici.

Pour plus d’informations sur l’Explorateur d’API , consultez Présentation de l’ApiExplorer dans ASP.NET Core .

Opération d’API

Une opération d’API représente une action ou une fonctionnalité spécifique qu’une API fournit. Dans ASP.NET Core, cela correspond à :

• Méthodes d’action du contrôleur dans les API de style MVC
• Gestionnaires de routage dans des API minimales

Chaque opération est définie par sa méthode HTTP (GET, , POST, PUTetc.), chemin d’accès, paramètres et réponses.

Point de terminaison d’API

Un point de terminaison d’API est une URL spécifique :

• Cela représente une ressource ou une fonctionnalité spécifique exposée par l’API.
• Fournit l’adresse exacte à laquelle un client doit envoyer une requête HTTP afin d’interagir avec une opération d’API particulière.

Un point de terminaison est une combinaison de l’URL de base de l’API et d’un chemin spécifique vers la ressource souhaitée, ainsi que les méthodes HTTP prises en charge :

• Pour les API basées sur le contrôleur, les points de terminaison combinent le modèle de routage avec le contrôleur et l’action.
• Pour les API minimales, les points de terminaison sont explicitement définis avec app.MapGet(), app.MapPost()etc.

Par exemple, le api/products/{id} point de terminaison qui prend en charge les opérations suivantes :

• GET /api/products/{id}
• PUT /api/products/{id}
• PATCH /api/products/{id}
• Delete /api/products/{id}
• HEAD /api/products/{id}

Les points de terminaison incluent souvent des paramètres de requête, par exemple, GET /api/products?category=electronics&sort=price

OpenAPI Documentation

Dans le contexte d’OpenAPI, la documentation décrit l’API dans son ensemble, y compris tous ses points de terminaison et opérations. OpenAPI offre un moyen structuré de documenter des API, ce qui facilite la compréhension par les développeurs de la façon d’interagir avec eux.

Les opérations d’API sont le principal objectif de la documentation OpenAPI. La spécification OpenAPI organise la documentation par opérations, qui sont regroupées par chemins d’accès (points de terminaison). Chaque opération est décrite avec des détails tels que des paramètres, des corps de requête, des réponses, etc. Ce format structuré permet aux outils de générer automatiquement des bibliothèques clientes, des stubs de serveur et de la documentation interactive.

Dans un document OpenAPI :

• Le document entier décrit l’API dans son ensemble
• Chaque élément de chemin d’accès (par exemple /api/products/{id}) représente un point de terminaison
• Sous chaque chemin d’accès, les méthodes HTTP (GET, POST, PUT, etc.) définissent les opérations
• Chaque opération contient des détails sur les paramètres, le corps de la demande, les réponses, etc.

Exemple au format JSON OpenAPI :

json{
  "paths": {
    "/api/products/{id}": {  // This is the endpoint
      "get": {  // This is the operation
        "summary": "Get a product by ID",
        "parameters": [...],
        "responses": {...}
      },
      "put": {  // Another operation on the same endpoint
        "summary": "Update a product",
        "parameters": [...],
        "responses": {...}
      }
    }
  }
}

Comparaison d’API, d’opérations d’API et de point de terminaison d’API

Le tableau suivant résume les différences entre une API, une opération d’API et un point de terminaison d’API :

Concept	Opération d’API	Point de terminaison d’API
Définition	Description logique d’une action d’API : méthode + chemin + comportement	Itinéraire HTTP configuré réel qui écoute les requêtes
niveau	Conceptuelle, quelle action peut se produire	Concrète, quelle URL et méthode sont mises en correspondance
Lié à	Conception/spécification de l’API OpenAPI	routage ASP.NET Core au moment de l’exécution
Décrit	Ce que fait l’API, par exemple, « créer un produit »	Où et comment l’appeler, par exemple, POST https://localhost:7099/api/products, POST https://contoso.com/api/products
Dans ASP.NET Core	Actions du contrôleur ou méthodes d’API minimales, avant la résolution du routage	Objets de point de terminaison résolus au moment de l’exécution

Code source OpenAPI d’ASP.NET Core sur GitHub

• AddOpenApi
• OpenApiDocumentService
• OpenApiOptions

Ressources complémentaires

• Authentification et autorisation dans les API minimales