OpenAPI-Dokumente generieren

Das Paket Microsoft.AspNetCore.OpenApi bietet integrierte Unterstützung für die OpenAPI-Dokumentgenerierung in ASP.NET Core. Das 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
• Unterstützung für das Generieren mehrerer OpenAPI-Dokumente aus einer einzelnen App
• Nutzt die Unterstützung des JSON-Schemas, das von System.Text.Json bereitgestellt wird.
• ist mit nativem AOT kompatibel.

Paketinstallation

Installieren Sie das Paket Microsoft.AspNetCore.OpenApi:

Visual Studio

Führen Sie den folgenden Befehl in der Paket-Manager-Konsole aus:

Install-Package Microsoft.AspNetCore.OpenApi

.NET CLI

Führen Sie den folgenden Befehl aus:

dotnet add package Microsoft.AspNetCore.OpenApi

Konfigurieren der OpenAPI-Dokumentgenerierung

Der folgende Code führt folgende Aktionen aus:

• Fügt OpenAPI-Dienste hinzu.
• Aktiviert den Endpunkt für die Anzeige des OpenAPI-Dokuments im JSON-Format.

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi();

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

app.Run();

Starten Sie die App, und navigieren Sie zu https://localhost:<port>/openapi/v1.json, um das generierte OpenAPI-Dokument anzuzeigen.

Optionen zum Anpassen der OpenAPI-Dokumentgenerierung

In den folgenden Abschnitten wird veranschaulicht, wie Sie die OpenAPI-Dokumentgenerierung anpassen.

Anpassen des OpenAPI-Dokumentnamens

Jedes OpenAPI-Dokument in einer App hat einen eindeutigen Namen. Der registrierte Standarddokumentname ist v1.

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

Der Dokumentname kann geändert werden, indem der Name als Parameter an den AddOpenApi-Aufruf übergeben wird.

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

Der Dokumentname wird an mehreren Stellen in der OpenAPI-Implementierung angezeigt.

Beim Abrufen des generierten OpenAPI-Dokuments wird der Dokumentname als documentName-Parameterargument in der Anforderung angegeben. Die folgenden Anforderungen lösen die Dokumente v1 und internal auf.

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

Anpassen der OpenAPI-Version eines generierten Dokuments

Standardmäßig generiert die OpenAPI-Dokumentgenerierung ein Dokument, das mit v3.0 der OpenAPI-Spezifikation kompatibel ist. Der folgende Code veranschaulicht, wie die Standardversion des OpenAPI-Dokuments geändert wird:

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

Anpassen der OpenAPI-Endpunktroute

Standardmäßig macht der über einen Aufruf von MapOpenApi registrierte OpenAPI-Endpunkt das Dokument am /openapi/{documentName}.json-Endpunkt verfügbar. Der folgende Code veranschaulicht, wie Sie die Route anpassen, mit der das OpenAPI-Dokument registriert ist:

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

Der documentName-Routenparameter kann aus der Endpunktroute entfernt werden, dies wird aber nicht empfohlen. Wenn der Routenparameter documentName aus der Endpunktroute entfernt wird, versucht das Framework, den Dokumentnamen aus dem Abfrageparameter aufzulösen. Wenn documentName weder in der Route noch in der Abfrage angegeben wird, kann das zu unerwartetem Verhalten führen.

Anpassen des OpenAPI-Endpunkts

Da das OpenAPI-Dokument über einen Routenhandler-Endpunkt bereitgestellt wird, stehen alle Anpassungen, die für standardmäßige minimale Endpunkte verfügbar sind, für den OpenAPI-Endpunkt zur Verfügung.

Einschränken des Zugriffs auf das OpenAPI-Dokument auf autorisierte Benutzer:innen

Der OpenAPI-Endpunkt aktiviert standardmäßig keine Autorisierungsprüfungen. Autorisierungsprüfungen können jedoch auf das OpenAPI-Dokument angewendet werden. Mit dem folgenden Code wird der Zugriff auf das OpenAPI-Dokument beispielsweise auf Personen mit der Rolle tester beschränkt:

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

Zwischenspeichern des generierten OpenAPI-Dokuments

Das OpenAPI-Dokument wird jedes Mal erneut generiert, wenn eine Anforderung an den OpenAPI-Endpunkt gesendet wird. Durch die erneute Generierung können die Transformatoren dynamisch den Anwendungszustand in ihre Vorgänge integrieren. So können Sie z. B. eine Anforderung mit Details des HTTP-Kontexts neu generieren. Dementsprechend kann das OpenAPI-Dokument zwischengespeichert werden, um die Ausführung der Dokumentgenerierungspipeline für jede HTTP-Anforderung zu vermeiden.

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

Generieren von OpenAPI-Dokumenten zur Erstellungszeit

In typischen Webanwendungen werden OpenAPI-Dokumente zur Laufzeit generiert und über eine HTTP-Anforderung an den Anwendungsserver bereitgestellt.

In einigen Szenarien ist es hilfreich, das OpenAPI-Dokument während des Buildschritts der Anwendung zu generieren. Zu diesen Szenarien gehören:

• Generieren der OpenAPI-Dokumentation, die in die Quellcodeverwaltung übernommen wird.
• Generieren der OpenAPI-Dokumentation, die für spezifikationsbasierte Integrationstests verwendet wird.
• Generieren der OpenAPI-Dokumentation, die statisch vom Webserver bereitgestellt wird.

Um Unterstützung für das Generieren von OpenAPI-Dokumenten zum Zeitpunkt der Erstellung hinzuzufügen, installieren Sie das Microsoft.Extensions.ApiDescription.Server-Paket:

Visual Studio

Führen Sie den folgenden Befehl in der Paket-Manager-Konsole aus:

Install-Package Microsoft.Extensions.ApiDescription.Server

.NET CLI

Führen Sie den folgenden Befehl in dem Verzeichnis aus, das die Projektdatei enthält:

dotnet add package Microsoft.Extensions.ApiDescription.Server

Bei der Installation generiert dieses Paket automatisch die open API-Dokumente, die der Anwendung während des Builds zugeordnet sind, und füllt sie in das Ausgabeverzeichnis der Anwendung auf.

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

Anpassen der Erstellung von Dokumenten

Ändern des Ausgabeverzeichnisses der generierten Open-API-Datei

Standardmäßig wird das generierte OpenAPI-Dokument in das Ausgabeverzeichnis der Anwendung ausgegeben. Um den Speicherort der ausgegebenen Datei zu ändern, legen Sie den Zielpfad in der OpenApiDocumentsDirectory Eigenschaft fest.

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

Der Wert der OpenApiDocumentsDirectory Datei wird relativ zur Projektdatei aufgelöst. Wenn Sie den ./ obigen Wert verwenden, wird das OpenAPI-Dokument im selben Verzeichnis wie die Projektdatei ausgegeben.

Ändern des Ausgabedateinamens

Standardmäßig hat das generierte OpenAPI-Dokument denselben Namen wie die Projektdatei der Anwendung. Um den Namen der ausgegebenen Datei zu ändern, legen Sie das --file-name Argument in der OpenApiGenerateDocumentsOptions Eigenschaft fest.

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

Auswählen des zu generierenden OpenAPI-Dokuments

Einige Anwendungen können so konfiguriert werden, dass mehrere OpenAPI-Dokumente ausgegeben werden, für verschiedene Versionen einer API oder für die Unterscheidung zwischen öffentlichen und internen APIs. Standardmäßig gibt der Buildzeitdokument-Generator Dateien für alle Dokumente aus, die in einer Anwendung konfiguriert sind. Wenn Sie nur einen einzelnen Dokumentnamen ausgeben möchten, legen Sie das --document-name Argument in der OpenApiGenerateDocumentsOptions Eigenschaft fest.

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

Anpassen des Laufzeitverhaltens während der Erstellung von Dokumenten

Unter der Haube funktioniert die Erstellung von OpenAPI-Dokumentgenerierungsfunktionen durch Starten des Einstiegspunkts der Anwendung mit einer inert serverimplementierung. Dies ist eine Anforderung, genaue OpenAPI-Dokumente zu erstellen, da alle Informationen im OpenAPI-Dokument nicht statisch analysiert werden können. Da der Einstiegspunkt der Anwendung aufgerufen wird, wird jede Logik im Start der Anwendung aufgerufen. Dies umfasst Code, der Dienste in den DI-Container einschließt oder aus der Konfiguration liest. In einigen Szenarien ist es erforderlich, die Codepfade einzuschränken, die ausgeführt werden, wenn der Einstiegspunkt der Anwendung von der Erstellungszeit-Dokumentgenerierung aufgerufen wird. Zu diesen Szenarien gehören:

• Nicht aus bestimmten Konfigurationszeichenfolgen lesen.
• Datenbankbezogene Dienste werden nicht registriert.

Um zu verhindern, dass diese Codepfade von der Pipeline für die Buildzeitgenerierung aufgerufen werden, können sie hinter einer Überprüfung der Eintragsassembly wie folgt bedingt werden:

using System.Reflection;

var builder = WebApplication.CreateBuilder();

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