C# Academy · Lektion

OpenAPI-Dokumente generieren

Erstellen Sie maschinenlesbare API-Spezifikationen.

OpenAPI-Dokumente generieren ist eine kostenlose C# Academy-Lektion auf CoddyKit. Dies ist Lektion 3 von 4. Du kannst die komplette Lektion unten kostenlos lesen – dann übst du sie direkt im Browser mit einem integrierten Code-Editor und einem KI-Tutor rund um die Uhr. Sie ist Teil des C# Academy-Lernpfads, und dein Fortschritt wird über Web und CoddyKit-App synchronisiert. Der C# Academy-Kurs umfasst insgesamt 4 Lektionen.

Was ist OpenAPI?

OpenAPI ist eine standardisierte, maschinenlesbare Beschreibung einer HTTP-API. Daraus können Sie Dokumentation, Client-SDKs und Testwerkzeuge generieren.

.NET 9 bietet die Generierung von OpenAPI-Dokumenten bereits integriert und ersetzt bei vielen Anwendungen die ältere Abhängigkeit von Swashbuckle.

// OpenAPI document = JSON describing paths, schemas, params

Das Paket Microsoft.AspNetCore.OpenApi

Die integrierte Unterstützung befindet sich in Microsoft.AspNetCore.OpenApi. In .NET-9-Vorlagen ist das Paket bereits referenziert.

dotnet add package Microsoft.AspNetCore.OpenApi

AddOpenApi

Registrieren Sie den Dokumentgenerator mit AddOpenApi in Ihrer Dienstkonfiguration.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

MapOpenApi

MapOpenApi stellt das generierte Dokument an einem Endpunkt bereit. Standardmäßig wird es unter /openapi/v1.json bereitgestellt.

var app = builder.Build();

app.MapOpenApi();   // GET /openapi/v1.json

app.Run();

Auf die Entwicklung beschränken

Üblicherweise wird das Dokument nur in der Entwicklungsumgebung bereitgestellt, damit in der Produktion keine Informationen über Ihre API-Oberfläche preisgegeben werden.

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

Endpunkte beschreiben

OpenAPI-Metadaten werden aus Ihrem Code ergänzt. Verwenden Sie bei Endpunkten minimaler APIs WithSummary, WithDescription und WithTags.

app.MapGet("/products/{id}", (int id) => Results.Ok())
   .WithSummary("Get a product by id")
   .WithDescription("Returns a single product or 404.")
   .WithTags("Products");

Antworten dokumentieren

Geben Sie die Antworttypen und Statuscodes an, damit das Dokument sie korrekt auflistet.

app.MapGet("/products/{id}", (int id) => Results.Ok())
   .Produces<Product>(StatusCodes.Status200OK)
   .Produces(StatusCodes.Status404NotFound);

Dokumenttransformer

Passen Sie das gesamte Dokument – Titel, Version und Server – mit einem Dokumenttransformer an, den Sie an AddOpenApi übergeben.

builder.Services.AddOpenApi(options =>
{
    options.AddDocumentTransformer((doc, ctx, ct) =>
    {
        doc.Info.Title = "Catalog API";
        doc.Info.Version = "1.0";
        return Task.CompletedTask;
    });
});

Operationstransformer

Ein Operationstransformer passt einzelne Operationen an – beispielsweise, indem er jedem Endpunkt einen gemeinsamen Headerparameter hinzufügt.

options.AddOperationTransformer((operation, ctx, ct) =>
{
    operation.Responses.TryAdd("500",
        new OpenApiResponse { Description = "Server error" });
    return Task.CompletedTask;
});

Eine Benutzeroberfläche hinzufügen

Der integrierte Generator erstellt das JSON-Dokument, aber keine Benutzeroberfläche. Kombinieren Sie ihn mit einem Viewer wie Scalar oder Swagger UI.

// dotnet add package Scalar.AspNetCore
app.MapOpenApi();
app.MapScalarApiReference();  // interactive docs at /scalar/v1

Zur Buildzeit generieren

Sie können die OpenAPI-Datei während des Builds – ohne laufenden Server – mithilfe der Tools von Microsoft.Extensions.ApiDescription.Server ausgeben. Das ist praktisch für die Generierung von Clients in CI.

// .csproj
// <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
// produces obj/<App>.json on build

Kurzprüfung

Bestätigen Sie die Grundlagen von OpenAPI in .NET 9.

Zusammenfassung

Sie haben OpenAPI-Dokumente generiert:

AddOpenApi() registriert den Generator; MapOpenApi() stellt das JSON bereit.
Ergänzen Sie Endpunkte mit WithSummary, Produces und Tags.
Dokument- und Operationstransformer passen die Ausgabe an.
Kombinieren Sie den Generator mit Scalar oder Swagger UI für eine interaktive Ansicht.

Als Nächstes: versionierte APIs dokumentieren.

Häufig gestellte Fragen

Ist die Lektion „OpenAPI-Dokumente generieren“ kostenlos?

Ja — der vollständige Text von „OpenAPI-Dokumente generieren“ ist hier im Web kostenlos zu lesen. Um sie interaktiv zu üben (integrierter Code-Editor und 24/7 KI-Tutor) und den Rest des C# Academy-Kurses freizuschalten, upgrade auf CoddyKit PRO. Der C# Academy-Kurs umfasst insgesamt 4 Lektionen.

Was lerne ich in „OpenAPI-Dokumente generieren“?

Erstellen Sie maschinenlesbare API-Spezifikationen. Du übst C# Academy mit praktischem Code, den du direkt im Browser ausführst, und ein 24/7 KI-Tutor beantwortet deine Fragen während du die Lektion bearbeitest.

Brauche ich Erfahrung, um C# Academy zu starten?

Keine Vorkenntnisse erforderlich. C# Academy auf CoddyKit ist für Anfänger bis fortgeschrittene Lernende strukturiert, sodass du hier starten oder von Anfang an beginnen und in deinem eigenen Tempo voranschreiten kannst. Dies ist Lektion 3 von 4.

Wie lange dauert die Lektion „OpenAPI-Dokumente generieren“?

Die meisten CoddyKit-Lektionen dauern etwa 5–10 Minuten. Jede ist kompakt und interaktiv, sodass du stetig Fortschritte machst und genau dort weitermachst, wo du aufgehört hast – im Web und in der App.

Kann ich in dieser C# Academy-Lektion Code schreiben und ausführen?

Ja. Jede C# Academy-Lektion enthält einen integrierten Code-Editor, sodass du echten Code direkt in deinem Browser schreibst und ausführst und sofort KI-Feedback erhältst — ohne lokale Einrichtung erforderlich.

Alle Lektionen in diesem Kurs

← Zurück zu C# Academy