C# Academy · Lektion

Versionierte APIs dokumentieren

Stellen Sie Dokumentation für mehrere API-Versionen bereit.

Versionierte APIs dokumentieren ist eine kostenlose C# Academy-Lektion auf CoddyKit. Dies ist Lektion 4 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.

Ein Dokument pro Version

Wenn eine API mehrere Versionen hat, benötigen Sie normalerweise ein separates OpenAPI-Dokument für jede Version, damit Konsumenten nur die für sie relevanten Endpunkte sehen.

// /openapi/v1.json -> only v1 endpoints
// /openapi/v2.json -> only v2 endpoints

Der API-Versionsbeschreibungsanbieter

Asp.Versioning stellt IApiVersionDescriptionProvider bereit, das alle ermittelten API-Versionen auflistet. Sie durchlaufen diese Liste, um pro Version ein Dokument zu registrieren.

var provider = app.Services
    .GetRequiredService<IApiVersionDescriptionProvider>();

foreach (var desc in provider.ApiVersionDescriptions)
{
    // desc.GroupName is e.g. "v1", "v2"
}

Ein Dokument pro Version registrieren

Rufen Sie AddOpenApi einmal pro Versionsgruppe auf und benennen Sie jedes Dokument nach der jeweiligen Gruppe.

builder.Services
    .AddApiVersioning()
    .AddApiExplorer(o =>
    {
        o.GroupNameFormat = "'v'VVV";
        o.SubstituteApiVersionInUrl = true;
    });

builder.Services.AddOpenApi("v1");
builder.Services.AddOpenApi("v2");

Endpunkte dem richtigen Dokument zuordnen

Verwenden Sie einen Dokumenttransformer oder das Prädikat ShouldInclude, damit jedes Dokument nur die Endpunkte seiner Version enthält, die anhand des Gruppennamens abgeglichen werden.

builder.Services.AddOpenApi("v1", options =>
{
    options.ShouldInclude = description =>
        description.GroupName == "v1";
});

Die Dokumente bereitstellen

MapOpenApi stellt mit dem Standardmuster jedes benannte Dokument unter /openapi/{documentName}.json bereit.

app.MapOpenApi();
// /openapi/v1.json and /openapi/v2.json both available

Informationen pro Dokument festlegen

Geben Sie jedem Versionsdokument in einem Transformer einen eigenen Titel und eine eigene Version, damit die Dokumente sich selbst beschreiben.

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

Veraltete Versionen in der Dokumentation markieren

Wenn eine Version veraltet ist, weisen Sie in der Beschreibung ihres Dokuments darauf hin, damit Konsumenten den Warnhinweis in der Benutzeroberfläche sehen.

options.AddDocumentTransformer((doc, ctx, ct) =>
{
    if (ctx.DocumentName == "v1")
        doc.Info.Description = "DEPRECATED - migrate to v2.";
    return Task.CompletedTask;
});

Die Version in URLs ersetzen

SubstituteApiVersionInUrl = true ersetzt das Routentoken {version:apiVersion} im Dokument durch die konkrete Version (z. B. v1), sodass die Pfade übersichtlich dargestellt werden.

// Without: /api/v{version}/products
// With:    /api/v1/products

Eine Benutzeroberflächenregisterkarte pro Version

Die meisten Viewer können eine Dropdownliste mit allen Dokumenten anzeigen. Konfigurieren Sie die Benutzeroberfläche so, dass sie auf das JSON-Dokument jeder Version verweist.

app.MapScalarApiReference(options =>
{
    options.AddDocument("v1", "API v1", "/openapi/v1.json");
    options.AddDocument("v2", "API v2", "/openapi/v2.json");
});

Anfrage- und Antwortstrukturen dokumentieren

Da sich DTOs in v2 ändern können, geben Sie jeder Version eigene DTO-Typen. OpenAPI stellt dann automatisch unterschiedliche Schemas pro Dokument dar.

// V1 DTO
public record ProductV1(int Id, string Name);
// V2 DTO (breaking change)
public record ProductV2(int Id, string Title, decimal Price);

Alles zusammenführen

Der vollständige Ablauf: Versionierung und API Explorer konfigurieren, pro Version ein OpenApi-Dokument mit einem Filter registrieren, die Dokumente bereitstellen und die Benutzeroberfläche auf jedes Dokument verweisen lassen.

builder.Services.AddApiVersioning().AddApiExplorer(o =>
{
    o.GroupNameFormat = "'v'VVV";
    o.SubstituteApiVersionInUrl = true;
});
builder.Services.AddOpenApi("v1");
builder.Services.AddOpenApi("v2");
// ...
app.MapOpenApi();
app.MapScalarApiReference();

Kurzprüfung

Bestätigen Sie, wie versionierte Dokumente erstellt werden.

Zusammenfassung

Sie haben versionierte APIs dokumentiert:

Registrieren Sie mit AddOpenApi("vN") ein benanntes OpenAPI-Dokument pro Version.
IApiVersionDescriptionProvider listet die Versionen auf; ShouldInclude filtert die Endpunkte.
SubstituteApiVersionInUrl stellt konkrete versionierte Pfade dar.
Verweisen Sie die Benutzeroberfläche auf jedes Dokument, um eine Ansicht pro Version bereitzustellen.

Damit ist der Kurs zu Versionierung und OpenAPI abgeschlossen.

Häufig gestellte Fragen

Ist die Lektion „Versionierte APIs dokumentieren“ kostenlos?

Ja — der vollständige Text von „Versionierte APIs dokumentieren“ 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 „Versionierte APIs dokumentieren“?

Stellen Sie Dokumentation für mehrere API-Versionen bereit. 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 4 von 4.

Wie lange dauert die Lektion „Versionierte APIs dokumentieren“?

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