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 JSON-Schemaunterstützung, die von
System.Text.Json
bereitgestellt wird. - ist mit nativem AOT kompatibel.
Paketinstallation
Installieren Sie das Paket Microsoft.AspNetCore.OpenApi
:
Führen Sie den folgenden Befehl in der Paket-Manager-Konsole aus:
Install-Package Microsoft.AspNetCore.OpenApi -IncludePrerelease
Um Unterstützung für das Generieren von OpenAPI-Dokumenten zum Zeitpunkt der Erstellung hinzuzufügen, installieren Sie das Microsoft.Extensions.ApiDescription.Server
-Paket:
Führen Sie den folgenden Befehl in der Paket-Manager-Konsole aus:
Install-Package Microsoft.Extensions.ApiDescription.Server -IncludePrerelease
Konfigurieren der OpenAPI-Dokumentgenerierung
Der folgende Code führt folgende Aktionen aus:
- Fügt OpenAPI-Dienste hinzu.
- Aktiviert den Endpunkt zum Anzeigen 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.
Einschließen von OpenAPI-Metadaten in eine ASP.NET-Web-App
Einschließen von OpenAPI-Metadaten für Endpunkte
ASP.NET sammelt Metadaten von den Endpunkten der Web-App und verwendet sie zum Generieren eines OpenAPI-Dokuments.
In controllerbasierten Apps werden Metadaten aus Attributen wie [EndpointDescription]
, [HttpPost]
und [Produces]
gesammelt.
In minimalen APIs können Metadaten aus Attributen gesammelt werden, sie können aber auch mithilfe von Erweiterungsmethoden und anderen Strategien festgelegt werden, z. B. das Zurückgeben von TypedResults
von Routenhandlern.
Die folgende Tabelle enthält eine Übersicht über die gesammelten Metadaten und die Strategien zum Festlegen der Metadaten.
Metadaten | Attribut | Erweiterungsmethode | Weitere Strategien |
---|---|---|---|
Zusammenfassung | [EndpointSummary] |
WithSummary |
|
Beschreibung | [EndpointDescription] |
WithDescription |
|
Tags | [Tags] |
WithTags |
|
operationId | [EndpointName] |
WithName |
|
Parameter | [FromQuery] , [FromRoute] , [FromHeader] , [FromForm] |
||
Parameterbeschreibung | [Description] |
||
requestBody | [FromBody] |
Accepts |
|
Antworten | [Produces] , [ProducesProblem] |
Produces , ProducesProblem |
TypedResults |
Ausschließen von Endpunkten | [ExcludeFromDescription] |
ExcludeFromDescription |
ASP.NET Core sammelt keine Metadaten aus XML-Dokumentkommentaren.
In den folgenden Abschnitten wird veranschaulicht, wie Sie Metadaten in eine App integrieren, um das generierte OpenAPI-Dokument anzupassen.
Zusammenfassung und Beschreibung
Die Endpunktzusammenfassung und -beschreibung kann mit den [EndpointSummary]
- und [EndpointDescription]
-Attributen oder in minimalen APIs mit den WithSummary
- und WithDescription
-Erweiterungsmethoden festgelegt werden.
[EndpointSummary]
: EndpointSummaryAttribute[EndpointDescription]
: EndpointDescriptionAttributeWithSummary
: WithSummaryWithDescription
: WithDescription
Im folgenden Beispiel werden die verschiedenen Strategien zum Festlegen von Zusammenfassungen und Beschreibungen veranschaulicht.
Beachten Sie, dass die Attribute in der Delegatmethode und nicht in der app.MapGet-Methode platziert werden.
app.MapGet("/extension-methods", () => "Hello world!")
.WithSummary("This is a summary.")
.WithDescription("This is a description.");
app.MapGet("/attributes",
[EndpointSummary("This is a summary.")]
[EndpointDescription("This is a description.")]
() => "Hello world!");
Tags
OpenAPI unterstützt die Angabe von Tags auf jedem Endpunkt als Form der Kategorisierung.
In controllerbasierten Apps wird der Controllername automatisch als Tag auf jedem seiner Endpunkte hinzugefügt; dies kann jedoch mithilfe des [Tags]
-Attributs überschrieben werden.
In minimalen APIs können Tags entweder mithilfe des [Tags]
-Attributs oder der WithTags
-Erweiterungsmethode festgelegt werden.
[Tags]
: TagsAttributeWithTags
: WithTags
Im folgenden Beispiel werden die verschiedenen Strategien zum Festlegen von Tags veranschaulicht.
app.MapGet("/extension-methods", () => "Hello world!")
.WithTags("todos", "projects");
app.MapGet("/attributes",
[Tags("todos", "projects")]
() => "Hello world!");
operationId
OpenAPI unterstützt eine operationId für jeden Endpunkt als eindeutigen Bezeichner oder Namen für den Vorgang.
In controllerbasierten Apps kann die operationId mithilfe des [EndpointName]
-Attributs festgelegt werden.
In minimalen APIs kann die operationId entweder mithilfe des [EndpointName]
-Attributs oder der WithName
-Erweiterungsmethode festgelegt werden.
[EndpointName]
: EndpointNameAttributeWithName
: WithName
Im folgenden Beispiel werden die verschiedenen Strategien zum Festlegen der operationId veranschaulicht.
app.MapGet("/extension-methods", () => "Hello world!")
.WithName("FromExtensionMethods");
app.MapGet("/attributes",
[EndpointName("FromAttributes")]
() => "Hello world!");
Parameter
OpenAPI unterstützt Anmerkungen zu Pfad, Abfragezeichenfolge, Header und cookie-Parametern, die von einer API genutzt werden.
Das Framework leitet die Typen der Anforderungsparameter automatisch aus der Signatur des Routenhandlers ab.
Das [Description]
-Attribut kann verwendet werden, um eine Beschreibung für einen Parameter bereitzustellen.
Im folgenden Beispiel wird veranschaulicht, wie eine Beschreibung für einen Parameter festgelegt wird.
app.MapGet("/attributes",
([Description("This is a description.")] string name) => "Hello world!");
requestBody
Um den Typ der Eingaben zu definieren, die als Anforderungstext übermittelt werden, konfigurieren Sie die Eigenschaften mit der Accepts-Methode, um den Objekt- und Inhaltstyp zu definieren, die vom Anforderungshandler erwartet werden. Im nachstehenden Beispiel akzeptiert der Endpunkt ein Todo
-Objekt im Anforderungstext mit dem erwarteten Inhaltstyp application/xml
.
app.MapPost("/todos/{id}", (int id, Todo todo) => ...)
.Accepts<Todo>("application/xml");
Zusätzlich zur Accepts-Erweiterungsmethode kann ein Parametertyp durch Implementierung der IEndpointParameterMetadataProvider-Schnittstelle seine eigene Anmerkung beschreiben. Beispielsweise fügt der folgende Todo
-Typ eine Anmerkung hinzu, die einen Anforderungstext mit dem Inhaltstyp application/xml
erfordert.
public class Todo : IEndpointParameterMetadataProvider
{
public static void PopulateMetadata(ParameterInfo parameter, EndpointBuilder builder)
{
builder.Metadata.Add(new AcceptsMetadata(["application/xml", "text/xml"], typeof(XmlBody)));
}
}
Falls keine explizite Anmerkung angegeben wird, versucht das Framework, den Standardanforderungstyp zu bestimmen, wenn es einen Anforderungstextparameter im Endpunkthandler gibt. Der Rückschluss verwendet die folgende Heuristik, um die Anmerkung zu generieren:
- Anforderungstextparameter, die über das Attribut
[FromForm]
aus einem Formular gelesen werden, werden mit dem Inhaltstypmultipart/form-data
beschrieben. - Alle anderen Anforderungstextparameter werden mit dem Inhaltstyp
application/json
beschrieben. - Der Anforderungstext wird als optional behandelt, wenn er Nullwerte zulässt oder die AllowEmpty-Eigenschaft für das
FromBody
-Attribut festgelegt ist.
Beschreiben von Antworttypen
OpenAPI unterstützt die Bereitstellung einer Beschreibung der von einer API zurückgegebenen Antworten. Minimal-APIs unterstützen drei Strategien zum Festlegen des Antworttyps eines Endpunkts:
- Über die Erweiterungsmethode Produces für den Endpunkt.
- Über das Attribut
ProducesResponseType
für den Routenhandler. - Durch Zurückgeben von TypedResults aus dem Routenhandler.
Mit der Erweiterungsmethode Produces
können einem Endpunkt Produces
-Metadaten hinzugefügt werden. Wenn keine Parameter angegeben werden, füllt die Erweiterungsmethode die Metadaten für den Zieltyp mit dem Statuscode 200
und dem Inhaltstyp application/json
auf.
app.MapGet("/todos", async (TodoDb db) => await db.Todos.ToListAsync())
.Produces<IList<Todo>>();
Die Verwendung von TypedResults in der Implementierung des Routenhandlers eines Endpunkts schließt automatisch die Metadaten des Antworttyps für den Endpunkt ein. Der nachstehende Code versieht beispielsweise den Endpunkt automatisch mit einer Antwort unter dem Statuscode 200
mit dem Inhaltstyp application/json
.
app.MapGet("/todos", async (TodoDb db) =>
{
var todos = await db.Todos.ToListAsync();
return TypedResults.Ok(todos);
});
Festlegen von Antworten für ProblemDetails
Beim Festlegen des Antworttyps für Endpunkte, die eine ProblemDetails-Antwort zurückgeben können, kann die Erweiterungsmethode ProducesProblem oder ProducesValidationProblem oder TypedResults.Problem verwendet werden, um den entsprechenden Kommentar zu den Metadaten des Endpunkts hinzuzufügen.
Wenn es keine expliziten Anmerkungen gibt, die mittels einer dieser Strategien bereitgestellt werden, versucht das Framework, einen Standardantworttyp zu bestimmen, indem es die Signatur der Antwort untersucht. Diese Standardantwort wird unter dem Statuscode 200
in der OpenAPI-Definition eingetragen.
Mehrere Antworttypen
Wenn ein Endpunkt verschiedene Antworttypen in verschiedenen Szenarien zurückgeben kann, können Sie Metadaten auf folgende Weise bereitstellen:
Rufen Sie die Produces-Erweiterungsmethode mehrmals auf, wie im folgenden Beispiel gezeigt:
app.MapGet("/api/todoitems/{id}", async (int id, TodoDb db) => await db.Todos.FindAsync(id) is Todo todo ? Results.Ok(todo) : Results.NotFound()) .Produces<Todo>(StatusCodes.Status200OK) .Produces(StatusCodes.Status404NotFound);
Verwenden Sie
Results<TResult1,TResult2,TResultN>
in der Signatur und TypedResults im Textkörper des Handlers, wie im folgenden Beispiel gezeigt:app.MapGet("/book{id}", Results<Ok<Book>, NotFound> (int id, List<Book> bookList) => { return bookList.FirstOrDefault((i) => i.Id == id) is Book book ? TypedResults.Ok(book) : TypedResults.NotFound(); });
Die
Results<TResult1,TResult2,TResultN>
-Uniontypen deklarieren, dass ein Routenhandler mehrereIResult
implementierende konkrete Typen zurückgibt, und jeder dieser Typen, dieIEndpointMetadataProvider
implementieren, trägt zu den Metadaten des Endpunkts bei.Die Union-Typen implementieren implizite Umwandlungsoperatoren. Diese Operatoren ermöglichen dem Compiler, die in den generischen Argumenten angegebenen Typen automatisch in eine Instanz des Union-Typs zu konvertieren. Diese Fähigkeit hat den zusätzlichen Vorteil, dass zur Kompilierungszeit überprüft wird, ob ein Routenhandler nur die Ergebnisse zurückgibt, die er deklariert. Der Versuch, einen Typ zurückzugeben, der nicht als eines der generischen Argumente für
Results<TResult1,TResult2,TResultN>
deklariert wurde, führt zu einem Kompilierungsfehler.
Ausschließen von Endpunkten aus dem generierten Dokument
Standardmäßig werden alle Endpunkte, die in einer App definiert sind, in der generierten OpenAPI-Datei dokumentiert. Minimal-APIs unterstützen zwei Strategien zum Ausschließen eines bestimmten Endpunkts aus dem OpenAPI-Dokument, und zwar unter Verwendung von:
Im folgenden Beispiel werden die verschiedenen Strategien zum Ausschließen eines bestimmten Endpunkts aus dem generierten OpenAPI-Dokument veranschaulicht.
app.MapGet("/extension-method", () => "Hello world!")
.ExcludeFromDescription();
app.MapGet("/attributes",
[ExcludeFromDescription]
() => "Hello world!");
Einschließen von OpenAPI-Metadaten für Datentypen
C#-Klassen oder Datensätze, die in Anforderungs- oder Antworttexten verwendet werden, werden im generierten OpenAPI-Dokument als Schemata dargestellt. Standardmäßig werden nur öffentliche Eigenschaften im Schema dargestellt, aber es gibt auch JsonSerializerOptions, um Schemaeigenschaften für Felder zu erstellen.
Wenn PropertyNamingPolicy auf gemischte Groß-/Kleinschreibung eingestellt ist (dies ist der Standard in ASP.NET-Webanwendungen), werden Eigenschaftsnamen in einem Schema in der Form des Eigenschaftsnamens von Klassen oder Datensätzen mit gemischter Groß-/Kleinschreibung dargestellt. Das JsonPropertyNameAttribute kann für eine einzelne Eigenschaft verwendet werden, um den Namen der Eigenschaft im Schema anzugeben.
Typ und Format
Die JSON-Schemabibliothek ordnet Standard-C#-Typen dem OpenAPI-type
und -format
wie folgt zu:
C#-Typ | OpenAPI type |
OpenAPI format |
---|---|---|
int | integer | int32 |
long | integer | int64 |
short | integer | int16 |
Byte | integer | uint8 |
float | Zahl | float |
double | Zahl | double |
Decimal | Zahl | double |
bool | boolean | |
Zeichenfolge | Zeichenfolge | |
char | Zeichenfolge | char |
byte[] | Zeichenfolge | Byte |
DateTimeOffset | Zeichenfolge | date-time |
DateOnly | Zeichenfolge | date |
TimeOnly | Zeichenfolge | time |
URI | Zeichenfolge | uri |
Guid | Zeichenfolge | uuid |
Objekt | Nicht angegeben. | |
dynamisch | Nicht angegeben. |
Beachten Sie, dass für Objekt- und dynamische Typen in OpenAPI kein Typ definiert ist, da diese Daten beliebiger Art enthalten können, einschließlich primitiver Typen wie int oder string.
type
und format
können auch mit einem Schematransformator festgelegt werden. So kann es zum Beispiel sein, dass Sie für das format
von Dezimaltypen decimal
anstelle von double
möchten.
Verwenden von Attributen zum Hinzufügen von Metadaten
ASP.NET verwendet Metadaten aus Attributen für Klassen- oder Datensatzeigenschaften, um Metadaten für die entsprechenden Eigenschaften des generierten Schemas festzulegen.
In der folgenden Tabelle werden Attribute aus dem Namespace System.ComponentModel
zusammengefasst, die Metadaten für das generierte Schema bereitstellen:
Attribute | Beschreibung |
---|---|
DescriptionAttribute | Legt die description einer Eigenschaft im Schema fest. |
RequiredAttribute | Markiert eine Eigenschaft im Schema als required . |
DefaultValueAttribute | Legt den default -Wert einer Eigenschaft im Schema fest. |
RangeAttribute | Legt den minimum und maximum -Wert einer Ganzzahl oder Zahl fest. |
MinLengthAttribute | Legt die minLength einer Zeichenfolge fest. |
MaxLengthAttribute | Legt die maxLength einer Zeichenfolge fest. |
RegularExpressionAttribute | Legt die pattern einer Zeichenfolge fest. |
Beachten Sie, dass diese Attribute in Controller-basierten Apps dem Vorgang Filter hinzufügen, um zu überprüfen, ob eingehende Daten die Einschränkungen erfüllen. In minimalen APIs legen diese Attribute die Metadaten im generierten Schema fest, aber die Überprüfung muss explizit über einen Endpunktfilter, in der Logik des Routenhandlers oder über ein Drittanbieterpaket ausgeführt werden.
Andere Metadatenquellen für generierte Schemata
erforderlich
Eigenschaften können mit dem Modifikator erforderlich auch als required
markiert werden.
enum
Enumerationstypen in C# sind ganzzahlbasiert, können aber als Zeichenfolgen in JSON mit einem JsonConverterAttribute und einem JsonStringEnumConverter dargestellt werden. Wenn ein Enumerationstyp als Zeichenfolge in JSON dargestellt wird, verfügt das generierte Schema über eine Eigenschaft enum
mit den Zeichenfolgenwerten der Enumeration.
Ein Enumerationstyp ohne JsonConverterAttribute wird im generierten Schema als type: integer
definiert.
Hinweis: Das AllowedValuesAttribute legt die enum
-Werte einer Eigenschaft nicht fest.
nullable
Eigenschaften, die als Nullwerte zulassend oder als Verweistyp definiert sind, haben im generierten Schema nullable: true
. Dies entspricht dem Standardverhalten des System.Text.Json-Deserialisierers, der null
als gültigen Wert für eine Nullable-Eigenschaft akzeptiert.
additionalProperties
Schemata werden standardmäßig ohne Assertion additionalProperties
generiert, was den Standardwert von true
impliziert. Dies entspricht dem Standardverhalten des System.Text.Json Deserializers, das im Hintergrund zusätzliche Eigenschaften in einem JSON-Objekt ignoriert.
Wenn die zusätzlichen Eigenschaften eines Schemas nur Werte eines bestimmten Typs aufweisen sollen, definieren Sie die Eigenschaft oder Klasse als eine Dictionary<string, type>
. Der Schlüsseltyp für das Wörterbuch muss string
sein. Dadurch wird ein Schema generiert, in dem additionalProperties
das Schema für „type“ als die erforderlichen Wertetypen angibt.
Metadaten für polymorphe Typen
Verwenden Sie die Attribute JsonPolymorphicAttribute und JsonDerivedTypeAttribute einer übergeordneten Klasse, um das Diskriminatorfeld und die Untertypen für einen polymorphen Typ anzugeben.
Die JsonDerivedTypeAttribute fügt dem Schema für jede Unterklasse das Diskriminatorfeld hinzu, wobei eine Enumeration den spezifischen Diskriminatorwert für die Unterklasse angibt. Dieses Attribut ändert auch den Konstruktor jeder abgeleiteten Klasse, um den Diskriminatorwert festzulegen.
Eine abstrakte Klasse mit einem JsonPolymorphicAttribute-Attribut weist ein discriminator
-Feld im Schema auf, aber eine konkrete Klasse mit einem JsonPolymorphicAttribute-Attribut verfügt nicht über ein discriminator
-Feld. OpenAPI erfordert, dass die Diskriminatoreigenschaft eine erforderliche Eigenschaft im Schema sein muss, aber da die Diskriminatoreigenschaft nicht in der konkreten Basisklasse definiert ist, kann das Schema kein discriminator
-Feld enthalten.
Hinzufügen von Metadaten mit einem Schematransformator
Ein Schematransformator kann verwendet werden, um alle Standardmetadaten zu überschreiben oder dem generierten Schema zusätzliche Metadaten hinzuzufügen, z. B. example
-Werte. Weitere Informationen finden Sie unter Verwenden von Schematransformatoren.
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 Autorisierungsüberprüfungen. Auf das OpenAPI-Dokument können jedoch Autorisierungsüberprüfungen 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();
Transformatoren für OpenAPI-Dokumente
In diesem Abschnitt wird veranschaulicht, wie OpenAPI-Dokumente mit Transformatoren angepasst werden.
Anpassen von OpenAPI-Dokumenten mit Transformatoren
Transformatoren bieten eine API zum Ändern des OpenAPI-Dokuments mit benutzerdefinierten Anpassungen. Transformatoren eignen sich z. B. für folgende Szenarien:
- Hinzufügen von Parametern zu allen Vorgängen in einem Dokument
- Ändern der Beschreibungen von Parametern oder Vorgängen
- Hinzufügen von Informationen auf oberster Ebene zum OpenAPI-Dokument
Transformatoren sind in drei Kategorien unterteilt:
- Dokumenttransformatoren haben Zugriff auf das gesamte OpenAPI-Dokument. Sie können verwendet werden, um globale Änderungen am Dokument vorzunehmen.
- Vorgangstransformatoren gelten jeweils für einen einzelnen Vorgang. Jeder einzelne Vorgang ist eine Kombination aus Pfad und HTTP-Methode. Sie können verwendet werden, um Parameter oder Antworten auf Endpunkten zu ändern.
- Schematransformatoren lassen sich auf jedes Schema im Dokument anwenden. Diese können verwendet werden, um das Schema von Anforderungs- oder Antworttexten oder geschachtelte Schemata zu ändern.
Transformer können über den Aufruf der AddDocumentTransformer
-Methode im OpenApiOptions
-Objekt im Dokument registriert werden. Der folgende Codeschnipsel zeigt verschiedene Möglichkeiten zum Registrieren von Transformatoren im Dokument:
- Registrieren eines Dokumenttransformators mithilfe eines Delegaten
- Registrieren eines Dokumenttransformators mithilfe einer Instanz von
IOpenApiDocumentTransformer
- Registrieren eines Dokumenttransformators mithilfe eines DI-fähigen
IOpenApiDocumentTransformer
- Registrieren eines Vorgangstransformators mithilfe eines Delegaten
- Registrieren eines Vorgangstransformators mithilfe einer Instanz von
IOpenApiOperationTransformer
. - Registrieren eines Vorgangstransformators mithilfe eines DI-fähigen
IOpenApiOperationTransformer
. - Registrieren eines Schematransformators mithilfe eines Delegaten.
- Registrieren eines Schematransformators mithilfe einer Instanz von
IOpenApiSchemaTransformer
. - Registrieren eines Schematransformators mithilfe eines DI-fähigen
IOpenApiSchemaTransformer
.
using Microsoft.AspNetCore.OpenApi;
using Microsoft.OpenApi.Models;
var builder = WebApplication.CreateBuilder();
builder.Services.AddOpenApi(options =>
{
options.AddDocumentTransformer((document, context, cancellationToken)
=> Task.CompletedTask);
options.AddDocumentTransformer(new MyDocumentTransformer());
options.AddDocumentTransformer<MyDocumentTransformer>();
options.AddOperationTransformer((operation, context, cancellationToken)
=> Task.CompletedTask);
options.AddOperationTransformer(new MyOperationTransformer());
options.AddOperationTransformer<MyOperationTransformer>();
options.AddSchemaTransformer((schema, context, cancellationToken)
=> Task.CompletedTask);
options.AddSchemaTransformer(new MySchemaTransformer());
options.AddSchemaTransformer<MySchemaTransformer>();
});
var app = builder.Build();
app.MapOpenApi();
app.MapGet("/", () => "Hello world!");
app.Run();
Ausführungsreihenfolge für Transformer
Transformer werden basierend auf der Registrierung in First-In-First-Out-Reihenfolge ausgeführt. Im folgenden Codeschnipsel hat der Dokumenttransformator Zugriff auf die vom Vorgangstransformator vorgenommenen Änderungen:
var builder = WebApplication.CreateBuilder();
builder.Services.AddOpenApi(options =>
{
options.AddOperationTransformer((operation, context, cancellationToken)
=> Task.CompletedTask);
options.AddDocumentTransformer((document, context, cancellationToken)
=> Task.CompletedTask);
});
var app = builder.Build();
app.MapOpenApi();
app.MapGet("/", () => "Hello world!");
app.Run();
Verwenden von Dokumenttransformatoren
Dokumenttransformer haben Zugriff auf ein Kontextobjekt, das Folgendes umfasst:
- den Namen des zu ändernden Dokuments
- Die Liste der diesem Dokument zugeordneten
ApiDescriptionGroups
. - Der bei der Dokumentgenerierung verwendete
IServiceProvider
.
Dokumenttransformatoren können auch das generierte OpenAPI-Dokument verändern. Im folgenden Beispiel wird ein Dokumenttransformator veranschaulicht, der dem OpenAPI-Dokument einige Informationen zur API hinzufügt.
using Microsoft.Extensions.DependencyInjection;
using Microsoft.AspNetCore.Builder;
var builder = WebApplication.CreateBuilder();
builder.Services.AddOpenApi(options =>
{
options.AddDocumentTransformer((document, context, cancellationToken) =>
{
document.Info = new()
{
Title = "Checkout API",
Version = "v1",
Description = "API for processing checkouts from cart."
};
return Task.CompletedTask;
});
});
var app = builder.Build();
app.MapOpenApi();
app.MapGet("/", () => "Hello world!");
app.Run();
Vom Dienst aktivierte Dokumenttransformatoren können Instanzen der Dokumentinstanz verwenden, um die App zu ändern. Im folgenden Beispiel wird ein Dokumenttransformator gezeigt, der den IAuthenticationSchemeProvider
-Dienst auf Authentifizierungsebene verwendet. Er überprüft, ob alle Schemas für JWT-Bearer in der App registriert sind, und fügt sie auf der obersten Ebene des OpenAPI-Dokuments hinzu:
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.AddOpenApi(options =>
{
options.AddDocumentTransformer<BearerSecuritySchemeTransformer>();
});
var app = builder.Build();
app.MapOpenApi();
app.MapGet("/", () => "Hello world!");
app.Run();
internal sealed class BearerSecuritySchemeTransformer(IAuthenticationSchemeProvider authenticationSchemeProvider) : IOpenApiDocumentTransformer
{
public async Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)
{
var authenticationSchemes = await authenticationSchemeProvider.GetAllSchemesAsync();
if (authenticationSchemes.Any(authScheme => authScheme.Name == "Bearer"))
{
var requirements = new Dictionary<string, OpenApiSecurityScheme>
{
["Bearer"] = new OpenApiSecurityScheme
{
Type = SecuritySchemeType.Http,
Scheme = "bearer", // "bearer" refers to the header name here
In = ParameterLocation.Header,
BearerFormat = "Json Web Token"
}
};
document.Components ??= new OpenApiComponents();
document.Components.SecuritySchemes = requirements;
}
}
}
Dokumenttransformatoren sind für die Dokumentinstanz eindeutig, der sie zugeordnet sind. Im folgenden Beispiel führt ein Transformator folgende Aktionen aus:
- Er registriert authentifizierungsbezogene Anforderungen für das Dokument
internal
. - Er lässt das Dokument
public
unverändert.
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.AddOpenApi("internal", options =>
{
options.AddDocumentTransformer<BearerSecuritySchemeTransformer>();
});
builder.Services.AddOpenApi("public");
var app = builder.Build();
app.MapOpenApi();
app.MapGet("/world", () => "Hello world!")
.WithGroupName("internal");
app.MapGet("/", () => "Hello universe!")
.WithGroupName("public");
app.Run();
internal sealed class BearerSecuritySchemeTransformer(IAuthenticationSchemeProvider authenticationSchemeProvider) : IOpenApiDocumentTransformer
{
public async Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)
{
var authenticationSchemes = await authenticationSchemeProvider.GetAllSchemesAsync();
if (authenticationSchemes.Any(authScheme => authScheme.Name == "Bearer"))
{
// Add the security scheme at the document level
var requirements = new Dictionary<string, OpenApiSecurityScheme>
{
["Bearer"] = new OpenApiSecurityScheme
{
Type = SecuritySchemeType.Http,
Scheme = "bearer", // "bearer" refers to the header name here
In = ParameterLocation.Header,
BearerFormat = "Json Web Token"
}
};
document.Components ??= new OpenApiComponents();
document.Components.SecuritySchemes = requirements;
// Apply it as a requirement for all operations
foreach (var operation in document.Paths.Values.SelectMany(path => path.Operations))
{
operation.Value.Security.Add(new OpenApiSecurityRequirement
{
[new OpenApiSecurityScheme { Reference = new OpenApiReference { Id = "Bearer", Type = ReferenceType.SecurityScheme } }] = Array.Empty<string>()
});
}
}
}
}
Verwenden von Vorgangstransformatoren
Vorgänge sind eindeutige Kombinationen von HTTP-Pfaden und -Methoden in einem OpenAPI-Dokument. Vorgangstransformatoren sind bei folgenden Änderungen hilfreich:
- Änderungen für jeden Endpunkt einer App oder
- Bedingte Änderungen an bestimmten Routen
Vorgangstransformer haben Zugriff auf ein Kontextobjekt, das Folgendes enthält:
- den Namen des Dokuments, zu dem der Vorgang gehört
ApiDescription
, das dem Vorgang zugeordnet ist.- Der bei der Dokumentgenerierung verwendete
IServiceProvider
.
Beispielsweise fügt der folgende Vorgangstransformator 500
als Antwortstatuscode hinzu, der von allen Vorgängen im Dokument unterstützt wird.
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.AddOpenApi(options =>
{
options.AddOperationTransformer((operation, context, cancellationToken) =>
{
operation.Responses.Add("500", new OpenApiResponse { Description = "Internal server error" });
return Task.CompletedTask;
});
});
var app = builder.Build();
app.MapOpenApi();
app.MapGet("/", () => "Hello world!");
app.Run();
Verwenden von Schematransformatoren
Schemata sind die Datenmodelle, die in Anforderungs- und Antworttexten in einem OpenAPI-Dokument verwendet werden. Schematransformatoren sind nützlich, wenn eine Änderung erfolgt:
- Sollte an jedem Schema im Dokument vorgenommen werden, oder
- Bedingte Änderungen an bestimmten Schemata.
Schematransformatoren haben Zugriff auf ein Kontextobjekt, das Folgendes enthält:
- Den Namen des Dokuments, zu dem der Vorgang gehört.
- Die JSON-Typinformationen, die dem Zielschema zugeordnet sind.
- Der bei der Dokumentgenerierung verwendete
IServiceProvider
.
Der folgende Schematransformator legt z. B. das format
von Dezimaltypen auf decimal
anstatt double
fest:
using Microsoft.AspNetCore.OpenApi;
var builder = WebApplication.CreateBuilder();
builder.Services.AddOpenApi(options => {
// Schema transformer to set the format of decimal to 'decimal'
options.AddSchemaTransformer((schema, context, cancellationToken) =>
{
if (context.JsonTypeInfo.Type == typeof(decimal))
{
schema.Format = "decimal";
}
return Task.CompletedTask;
});
});
var app = builder.Build();
app.MapOpenApi();
app.MapGet("/", () => new Body { Amount = 1.1m });
app.Run();
public class Body {
public decimal Amount { get; set; }
}
Zusätzliche Ressourcen
Minimal-APIs bieten über das Paket Microsoft.AspNetCore.OpenApi
integrierte Unterstützung für das Generieren von Informationen zu Endpunkten in einer App. Für das Verfügbarmachen der generierten OpenAPI-Definition über eine visuelle Benutzeroberfläche ist ein Paket eines Drittanbieters erforderlich. Informationen zur Unterstützung von OpenAPI in controllerbasierten APIs finden Sie in der .NET 9-Version dieses Artikels.
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.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
var app = builder.Build();
if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI();
}
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")
.WithOpenApi();
app.Run();
internal record WeatherForecast(DateTime Date, int TemperatureC, string? Summary)
{
public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}
Im hervorgehobenen Code oben:
Microsoft.AspNetCore.OpenApi
wird im nächsten Abschnitt erläutert.- AddEndpointsApiExplorer : Konfiguriert die App so, dass sie den API-Explorer verwendet, um Endpunkte mit Standardanmerkungen zu ermitteln und zu beschreiben.
WithOpenApi
setzt die Übereinstimmung von Standardanmerkungen, die vom API-Explorer generiert werden, mit denen, die aus demMicrosoft.AspNetCore.OpenApi
Paket erstellt wurden, außer Kraft. UseSwagger
fügt die Swagger Middleware hinzu.- „UseSwaggerUI“ ermöglicht eine eingebettete Version des Swagger UI-Tools.
- WithName: Der IEndpointNameMetadata auf dem Endpunkt wird für die Linkgenerierung verwendet und wird als Vorgangs-ID in der OpenAPI-Spezifikation des angegebenen Endpunkts behandelt.
WithOpenApi
wird später im Artikel erläutert.
Microsoft.AspNetCore.OpenApi
NuGet-Paket
ASP.NET Core stellt das Microsoft.AspNetCore.OpenApi
Paket bereit, um mit OpenAPI-Spezifikationen für Endpunkte zu interagieren. Das Paket verhält sich wie eine Verknüpfung zwischen den OpenAPI-Modellen, die im Microsoft.AspNetCore.OpenApi
Paket definiert sind, und den Endpunkten, die in minimalen APIs definiert sind. Das Paket stellt eine API bereit, welche die Parameter, Antworten und Metadaten eines Endpunkts untersucht, um einen OpenAPI-Anmerkungstyp zu erstellen, der zum Beschreiben eines Endpunkts verwendet wird.
Microsoft.AspNetCore.OpenApi
wird als PackageReference zu einer Projektdatei hinzugefügt:
<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>net7.0</TargetFramework>
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="7.0.*-*" />
<PackageReference Include="Swashbuckle.AspNetCore" Version="6.4.0" />
</ItemGroup>
</Project>
Wenn Swashbuckle.AspNetCore
mit Microsoft.AspNetCore.OpenApi
verwendet wird, muss Swashbuckle.AspNetCore
6.4.0 oder höher verwendet werden. Microsoft.OpenApi
1.4.3 oder höher ist erforderlich, um Kopierkonstruktoren in WithOpenApi
-Aufrufen zu verwenden.
Hinzufügen von OpenAPI-Anmerkungen zu Endpunkten über WithOpenApi
Durch Aufrufen von WithOpenApi
für den Endpunkt werden die Metadaten des Endpunkts ergänzt. Diese Metadaten können:
- In Drittanbieterpaketen wie Swashbuckle.AspNetCore verarbeitet werden.
- Auf der Benutzeroberfläche von Swagger oder in YAML oder JSON angezeigt werden, die zum Definieren der API erstellt wurden.
app.MapPost("/todoitems/{id}", async (int id, Todo todo, TodoDb db) =>
{
todo.Id = id;
db.Todos.Add(todo);
await db.SaveChangesAsync();
return Results.Created($"/todoitems/{todo.Id}", todo);
})
.WithOpenApi();
Ändern der OpenAPI-Anmerkung in WithOpenApi
Die WithOpenApi
Methode akzeptiert eine Funktion, die benutzt werden kann, um die OpenAPI-Anmerkung zu verändern. Im folgenden Code wird beispielsweise eine Beschreibung zum ersten Parameter des Endpunkts hinzugefügt:
app.MapPost("/todo2/{id}", async (int id, Todo todo, TodoDb db) =>
{
todo.Id = id;
db.Todos.Add(todo);
await db.SaveChangesAsync();
return Results.Created($"/todoitems/{todo.Id}", todo);
})
.WithOpenApi(generatedOperation =>
{
var parameter = generatedOperation.Parameters[0];
parameter.Description = "The ID associated with the created Todo";
return generatedOperation;
});
Hinzufügen von Vorgangs-IDs zu OpenAPI
Vorgangs-IDs werden verwendet, um einen bestimmten Endpunkt in OpenAPI eindeutig zu identifizieren. Mit der Erweiterungsmethode WithName
können Sie die für eine Methode verwendete Vorgangs-ID festlegen.
app.MapGet("/todoitems2", async (TodoDb db) =>
await db.Todos.ToListAsync())
.WithName("GetToDoItems");
Alternativ kann die OperationId
-Eigenschaft auch direkt für die OpenAPI-Anmerkung festgelegt werden.
app.MapGet("/todos", async (TodoDb db) => await db.Todos.ToListAsync())
.WithOpenApi(operation => new(operation)
{
OperationId = "GetTodos"
});
Hinzufügen von Tags zur OpenAPI-Beschreibung
OpenAPI unterstützt Tagobjekte zum Kategorisieren von Vorgängen. Diese Tags werden in der Regel zum Gruppieren von Vorgängen auf der Swagger-Benutzeroberfläche verwendet. Diese Tags können einem Vorgang hinzugefügt werden, indem Sie die Erweiterungsmethode WithTags für den Endpunkt mit den gewünschten Tags aufrufen.
app.MapGet("/todoitems", async (TodoDb db) =>
await db.Todos.ToListAsync())
.WithTags("TodoGroup");
Alternativ kann die Liste der OpenApiTags
über die OpenAPI-Anmerkung mittels der Erweiterungsmethode WithOpenApi
festgelegt werden.
app.MapGet("/todos", async (TodoDb db) => await db.Todos.ToListAsync())
.WithOpenApi(operation => new(operation)
{
Tags = new List<OpenApiTag> { new() { Name = "Todos" } }
});
Hinzufügen einer Endpunktzusammenfassung oder -beschreibung
Die Endpunktzusammenfassung und -beschreibung kann durch Aufrufen der WithOpenApi
-Erweiterungsmethode hinzugefügt werden. Im folgenden Code werden die Zusammenfassungen direkt in der OpenAPI-Anmerkung festgelegt.
app.MapGet("/todoitems2", async (TodoDb db) => await db.Todos.ToListAsync())
.WithOpenApi(operation => new(operation)
{
Summary = "This is a summary",
Description = "This is a description"
});
Ausschließen der OpenAPI-Beschreibung
Im folgenden Beispiel wird der /skipme
-Endpunkt von der Generierung einer OpenAPI-Beschreibung ausgeschlossen:
using Microsoft.AspNetCore.OpenApi;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
var app = builder.Build();
if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI();
}
app.UseHttpsRedirection();
app.MapGet("/swag", () => "Hello Swagger!")
.WithOpenApi();
app.MapGet("/skipme", () => "Skipping Swagger.")
.ExcludeFromDescription();
app.Run();
Markieren einer API als veraltet
Wenn Sie einen Endpunkt als veraltet markieren möchten, legen Sie für die OpenAPI-Anmerkung die Eigenschaft Deprecated
fest.
app.MapGet("/todos", async (TodoDb db) => await db.Todos.ToListAsync())
.WithOpenApi(operation => new(operation)
{
Deprecated = true
});
Beschreiben von Antworttypen
OpenAPI unterstützt die Bereitstellung einer Beschreibung der von einer API zurückgegebenen Antworten. Minimal-APIs unterstützen drei Strategien zum Festlegen des Antworttyps eines Endpunkts:
- Über die Erweiterungsmethode
Produces
für den Endpunkt - Über das Attribut
ProducesResponseType
für den Routenhandler - Durch Zurückgeben von
TypedResults
aus dem Routenhandler
Mit der Erweiterungsmethode Produces
können einem Endpunkt Produces
-Metadaten hinzugefügt werden. Wenn keine Parameter angegeben werden, füllt die Erweiterungsmethode die Metadaten für den Zieltyp mit dem Statuscode 200
und dem Inhaltstyp application/json
auf.
app
.MapGet("/todos", async (TodoDb db) => await db.Todos.ToListAsync())
.Produces<IList<Todo>>();
Die Verwendung von TypedResults
in der Implementierung des Routenhandlers eines Endpunkts schließt automatisch die Metadaten des Antworttyps für den Endpunkt ein. Der nachstehende Code versieht beispielsweise den Endpunkt automatisch mit einer Antwort unter dem Statuscode 200
mit dem Inhaltstyp application/json
.
app.MapGet("/todos", async (TodoDb db) =>
{
var todos = await db.Todos.ToListAsync());
return TypedResults.Ok(todos);
});
Festlegen von Antworten für ProblemDetails
Beim Festlegen des Antworttyps für Endpunkte, die eine ProblemDetails-Antwort zurückgeben können, kann die Erweiterungsmethode ProducesProblem, ProducesValidationProblem oder TypedResults.Problem
verwendet werden, um den entsprechenden Kommentar zu den Metadaten des Endpunkts hinzuzufügen. Beachten Sie, dass die Erweiterungsmethoden ProducesProblem
und ProducesValidationProblem
nicht mit Routengruppen in .NET 8 und früher verwendet werden können.
Wenn es keine expliziten Anmerkungen gibt, die mittels einer der oben genannten Strategien bereitgestellt werden, versucht das Framework, einen Standardantworttyp zu bestimmen, indem es die Signatur der Antwort untersucht. Diese Standardantwort wird unter dem Statuscode 200
in der OpenAPI-Definition eingetragen.
Mehrere Antworttypen
Wenn ein Endpunkt verschiedene Antworttypen in verschiedenen Szenarien zurückgeben kann, können Sie Metadaten auf folgende Weise bereitstellen:
Rufen Sie die
Produces
-Erweiterungsmethode mehrmals auf, wie im folgenden Beispiel gezeigt:app.MapGet("/api/todoitems/{id}", async (int id, TodoDb db) => await db.Todos.FindAsync(id) is Todo todo ? Results.Ok(todo) : Results.NotFound()) .Produces<Todo>(StatusCodes.Status200OK) .Produces(StatusCodes.Status404NotFound);
Verwenden Sie
Results<TResult1,TResult2,TResultN>
in der Signatur undTypedResults
im Textkörper des Handlers, wie im folgenden Beispiel gezeigt:app.MapGet("/book{id}", Results<Ok<Book>, NotFound> (int id, List<Book> bookList) => { return bookList.FirstOrDefault((i) => i.Id == id) is Book book ? TypedResults.Ok(book) : TypedResults.NotFound(); });
Die
Results<TResult1,TResult2,TResultN>
-Uniontypen deklarieren, dass ein Routenhandler mehrereIResult
implementierende konkrete Typen zurückgibt, und jeder dieser Typen, dieIEndpointMetadataProvider
implementieren, trägt zu den Metadaten des Endpunkts bei.Die Union-Typen implementieren implizite Umwandlungsoperatoren. Diese Operatoren ermöglichen dem Compiler, die in den generischen Argumenten angegebenen Typen automatisch in eine Instanz des Union-Typs zu konvertieren. Diese Fähigkeit hat den zusätzlichen Vorteil, dass zur Kompilierungszeit überprüft wird, ob ein Routenhandler nur die Ergebnisse zurückgibt, die er deklariert. Der Versuch, einen Typ zurückzugeben, der nicht als eines der generischen Argumente für
Results<TResult1,TResult2,TResultN>
deklariert wurde, führt zu einem Kompilierungsfehler.
Beschreiben von Anforderungstext und -parametern
Neben der Beschreibung der Typen, die von einem Endpunkt zurückgegeben werden, unterstützt OpenAPI auch Anmerkungen zu Eingaben, die von einer API genutzt werden. Diese Eingaben lassen sich in zwei Kategorien einteilen:
- Parameter, die im Pfad, in der Abfragezeichenfolge, in den Headern oder in Cookies enthalten sind
- Daten, die als Teil des Anforderungstexts übermittelt werden
Das Framework leitet die Typen der Anforderungsparameter im Pfad, in der Abfrage und in der Headerzeichenfolge automatisch aus der Signatur des Routenhandlers ab.
Um den Typ der Eingaben zu definieren, die als Anforderungstext übermittelt werden, konfigurieren Sie die Eigenschaften mit der Accepts
-Methode, um den Objekt- und Inhaltstyp zu definieren, die vom Anforderungshandler erwartet werden. Im nachstehenden Beispiel akzeptiert der Endpunkt ein Todo
-Objekt im Anforderungstext mit dem erwarteten Inhaltstyp application/xml
.
app.MapPost("/todos/{id}", (int id, Todo todo) => ...)
.Accepts<Todo>("application/xml");
Zusätzlich zur Erweiterungsmethode Accepts
kann ein Parametertyp durch Implementierung der IEndpointParameterMetadataProvider
-Schnittstelle seine eigene Anmerkung beschreiben. Beispielsweise fügt der folgende Todo
-Typ eine Anmerkung hinzu, die einen Anforderungstext mit dem Inhaltstyp application/xml
erfordert.
public class Todo : IEndpointParameterMetadataProvider
{
public static void PopulateMetadata(ParameterInfo parameter, EndpointBuilder builder)
{
builder.Metadata.Add(new ConsumesAttribute(typeof(Todo), isOptional: false, "application/xml"));
}
}
Falls keine explizite Anmerkung angegeben wird, versucht das Framework, den Standardanforderungstyp zu bestimmen, wenn es einen Anforderungstextparameter im Endpunkthandler gibt. Der Rückschluss verwendet die folgende Heuristik, um die Anmerkung zu generieren:
- Anforderungstextparameter, die über das Attribut
[FromForm]
aus einem Formular gelesen werden, werden mit dem Inhaltstypmultipart/form-data
beschrieben. - Alle anderen Anforderungstextparameter werden mit dem Inhaltstyp
application/json
beschrieben. - Der Anforderungstext wird als optional behandelt, wenn er Nullwerte zulässt oder die
AllowEmpty
-Eigenschaft für dasFromBody
-Attribut festgelegt ist.
Unterstützung der API-Versionsverwaltung
Minimal-APIs unterstützen über das Paket Asp.Versioning.Http die API-Versionsverwaltung. Beispiele für die Konfiguration der Versionsverwaltung mit Minimal-APIs finden Sie im Repository der API-Versionsverwaltung.
ASP.NET Core OpenAPI-Quellcode auf GitHub
Weitere Ressourcen
Eine minimale API-App kann die OpenAPI-Spezifikation für Routenhandler unter Verwendung von Swashbuckle beschreiben.
Informationen zur Unterstützung von OpenAPI in controllerbasierten APIs finden Sie in der .NET 9-Version dieses Artikels.
Der folgende Code ist eine typische ASP.NET Core-App mit OpenAPI-Unterstützung:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new() { Title = builder.Environment.ApplicationName,
Version = "v1" });
});
var app = builder.Build();
if (app.Environment.IsDevelopment())
{
app.UseSwagger(); // UseSwaggerUI Protected by if (env.IsDevelopment())
app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json",
$"{builder.Environment.ApplicationName} v1"));
}
app.MapGet("/swag", () => "Hello Swagger!");
app.Run();
Ausschließen der OpenAPI-Beschreibung
Im folgenden Beispiel wird der /skipme
-Endpunkt von der Generierung einer OpenAPI-Beschreibung ausgeschlossen:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
var app = builder.Build();
if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI(); // UseSwaggerUI Protected by if (env.IsDevelopment())
}
app.MapGet("/swag", () => "Hello Swagger!");
app.MapGet("/skipme", () => "Skipping Swagger.")
.ExcludeFromDescription();
app.Run();
Beschreiben von Antworttypen
Im folgenden Beispiel werden die integrierten Ergebnistypen verwendet, um die Antwort anzupassen:
app.MapGet("/api/todoitems/{id}", async (int id, TodoDb db) =>
await db.Todos.FindAsync(id)
is Todo todo
? Results.Ok(todo)
: Results.NotFound())
.Produces<Todo>(StatusCodes.Status200OK)
.Produces(StatusCodes.Status404NotFound);
Hinzufügen von Vorgangs-IDs zur OpenAPI
app.MapGet("/todoitems2", async (TodoDb db) =>
await db.Todos.ToListAsync())
.WithName("GetToDoItems");
Hinzufügen von Tags zur OpenAPI-Beschreibung
Im folgenden Code wird ein OpenAPI-Gruppierungstag verwendet:
app.MapGet("/todoitems", async (TodoDb db) =>
await db.Todos.ToListAsync())
.WithTags("TodoGroup");