OpenAPI-Unterstützung in ASP.NET Core-API-Apps

ASP.NET Core unterstützt die Generierung von OpenAPI-Dokumenten in controllerbasierten und minimalen APIs-Apps. Die OpenAPI-Spezifikation ist ein gegenüber der Programmiersprache agnostischer Standard zum Dokumentieren von HTTP-APIs. Dieser Standard wird in ASP.NET Core-Apps durch eine Kombination aus integrierten APIs und Open-Source-Bibliotheken unterstützt. Es gibt drei wichtige Aspekte für die OpenAPI-Integration in eine Anwendung:

• Generieren von Informationen zu den Endpunkten in der App
• Sammeln der Informationen in einem Format, das dem OpenAPI-Schema entspricht
• Verfügbarmachen des generierten OpenAPI-Dokuments über eine visuelle Benutzeroberfläche oder eine serialisierte Datei

ASP.NET Core-Apps bieten über das Microsoft.AspNetCore.OpenApi-Paket integrierte Unterstützung für das Generieren von Informationen zu Endpunkten in einer App.

Der folgende Code ist aus der minimalen Web-API-Vorlage von ASP.NET Core generiert und verwendet 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);
}

Im hervorgehobenen Code oben:

• AddOpenApi registriert Dienste, die für die OpenAPI-Dokumentgenerierung erforderlich sind, im DI-Container der Anwendung.
• MapOpenApi fügt der Anwendung einen Endpunkt zum Anzeigen des OpenAPI-Dokuments hinzu, das in JSON serialisiert wurde. Der OpenAPI-Endpunkt ist auf die Entwicklungsumgebung beschränkt, um das Risiko der Offenlegung sensibler Informationen zu minimieren und die Schwachstellen in der Produktion zu reduzieren.

Microsoft.AspNetCore.OpenApi NuGet-Paket

Das Microsoft.AspNetCore.OpenApi-Paket bietet folgende Funktionen:

• Unterstützung für das Generieren von OpenAPI-Dokumenten zur Laufzeit und Zugriff darauf über einen Endpunkt in der Anwendung
• Unterstützung für „Transformator“-APIs, die das Ändern des generierten Dokuments ermöglichen

Um das Microsoft.AspNetCore.OpenApi-Paket zu verwenden, fügen Sie es einer Projektdatei als PackageReference hinzu:

<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>

Um mehr über das Microsoft.AspNetCore.OpenApi-Paket zu erfahren, siehe OpenAPI-Dokumente generieren.

Microsoft.Extensions.ApiDescription.Server NuGet-Paket

Das Microsoft.Extensions.ApiDescription.Server-Paket bietet Unterstützung für das Generieren von OpenAPI-Dokumenten zur Erstellungszeit und für ihre Serialisierung.

Durch Hinzufügen als PackageReference zu einer Projektdatei können Sie Microsoft.Extensions.ApiDescription.Server verwenden. Die Dokumentgenerierung zur Erstellungszeit wird durch Festlegen der OpenApiGenerateDocuments-Eigenschaft aktiviert. Standardmäßig wird das generierte OpenAPI-Dokument im obj-Verzeichnis gespeichert. Sie können das Ausgabeverzeichnis jedoch anpassen, indem Sie die OpenApiDocumentsDirectory-Eigenschaft festlegen.

<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>

ASP.NET Core OpenAPI-Quellcode auf GitHub

• AddOpenApi
• OpenApiDocumentService
• OpenApiOptions

Weitere Ressourcen

• Authentifizierung und Autorisierung in Minimal-API-Apps