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>

API v. API-Vorgang v. API-Endpunkt

In den folgenden Abschnitten werden die Unterschiede zwischen einer API, einem API-Endpunkt und einem API-Vorgang im Kontext der ASP.NET Core- und OpenAPI-Dokumentation erläutert.

API (Anwendungsprogrammierschnittstelle)

Eine API ist eine Reihe von Regeln und Protokollen zum Erstellen und Interagieren mit Softwareanwendungen. Es definiert, wie verschiedene Softwarekomponenten kommunizieren sollen. In der allgemeinen Webentwicklung bezieht sich "API" in der Regel auf einen Webdienst, der Funktionen über HTTP verfügbar macht.

In ASP.NET Core wird eine API in der Regel mit Controllern oder minimalen APIs erstellt, die eingehende HTTP-Anforderungen verarbeiten und Antworten zurückgeben.

ASP.NET Die internen Benennungskonventionen von Core verwenden manchmal "API" unterschiedlich. Im API-Explorer stellt eine "ApiDescription" beispielsweise einen API-Vorgang anstelle des vollständigen API-Diensts dar. Diese Unterscheidung spiegelt interne Benennungskonventionen wider und unterscheidet sich manchmal von der hier verwendeten breiteren Definition.

Weitere Informationen zum API-Explorer finden Sie unter "Einführung in apiExplorer" in ASP.NET Core .

API-Vorgang

Ein API-Vorgang stellt eine bestimmte Aktion oder Funktion dar, die eine API bereitstellt. In ASP.NET Core entspricht dies:

• Controlleraktionsmethoden in MVC-Stil-APIs
• Routinghandler in minimalen APIs

Jeder Vorgang wird durch seine HTTP-Methode (GET, POST, PUTusw.), Pfad, Parameter und Antworten definiert.

API-Endpunkt

Ein API-Endpunkt ist eine bestimmte URL:

• Dies stellt eine bestimmte Ressource oder Funktionalität dar, die von der API verfügbar gemacht wird.
• Stellt die genaue Adresse bereit, an die ein Client eine HTTP-Anforderung senden muss, um mit einem bestimmten API-Vorgang zu interagieren.

Ein Endpunkt ist eine Kombination aus der Basis-URL der API und einem bestimmten Pfad zur gewünschten Ressource sowie die unterstützten HTTP-Methoden:

• Für controllerbasierte APIs kombinieren Endpunkte die Routenvorlage mit Controller und Aktion.
• Für minimale APIs werden Endpunkte explizit mit app.MapGet(), , app.MapPost()usw. definiert.

Zum Beispiel der Endpunkt, der api/products/{id} die folgenden Vorgänge unterstützt:

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

Endpunkte enthalten häufig Abfrageparameter, z. B. GET /api/products?category=electronics&sort=price

OpenAPI-Dokumentation

Im Kontext von OpenAPI beschreibt die Dokumentation die API als Ganzes, einschließlich aller Endpunkte und Vorgänge. OpenAPI bietet eine strukturierte Möglichkeit zum Dokumentieren von APIs, sodass Entwickler leichter verstehen können, wie sie mit ihnen interagieren.

API-Vorgänge sind der primäre Schwerpunkt der OpenAPI-Dokumentation. Die OpenAPI-Spezifikation organisiert die Dokumentation nach Vorgängen, die nach Pfaden (Endpunkten) gruppiert sind. Jeder Vorgang wird mit Details wie Parametern, Anforderungstexten, Antworten und mehr beschrieben. Mit diesem strukturierten Format können Tools Clientbibliotheken, Server-Stubs und interaktive Dokumentation automatisch generieren.

In einem OpenAPI-Dokument:

• Das gesamte Dokument beschreibt die API als Ganzes.
• Jedes Pfadelement (wie /api/products/{id}) stellt einen Endpunkt dar.
• Unter jedem Pfad definieren die HTTP-Methoden (GET, POST, PUTusw.) die Vorgänge.
• Jeder Vorgang enthält Details zu Parametern, Anforderungstext, Antworten usw.

Beispiel im OpenAPI-JSON-Format:

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": {...}
      }
    }
  }
}

Vergleich von API, API-Vorgängen und API-Endpunkten

In der folgenden Tabelle werden die Unterschiede zwischen einer API, einem API-Vorgang und einem API-Endpunkt zusammengefasst:

Begriff	API-Vorgang	API-Endpunkt
Definition	Eine logische Beschreibung einer API-Aktion: Methode + Pfad + Verhalten	Die tatsächliche konfigurierte HTTP-Route, die auf Anforderungen lauscht
Grad	Konzeptuell, welche Aktion geschehen kann	Welche konkrete URL und Methode sind zugeordnet?
Gebunden an	OpenAPI-API-Entwurf/Spezifikation	ASP.NET Core-Routing zur Laufzeit
Beschreibt	Funktionsweise der API, z. B. "Produkt erstellen"	Wo und wie man es aufruft, zum Beispiel POST https://localhost:7099/api/products, POST https://contoso.com/api/products
In ASP.NET Core	Controlleraktionen oder Minimale API-Methoden, bevor die Routing-Auflösung erfolgt.	Endpunktobjekte wurden zur Laufzeit aufgelöst

ASP.NET Core OpenAPI-Quellcode auf GitHub

• AddOpenApi
• OpenApiDocumentService
• OpenApiOptions

Weitere Ressourcen

• Authentifizierung und Autorisierung in Minimal-API-Apps