C# Academy · Lekcja

Dokumentowanie wersjonowanych API

Udostępniaj dokumentację dla wielu wersji API.

Dokumentowanie wersjonowanych API to bezpłatna lekcja C# Academy na CoddyKit. To lekcja 4 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej C# Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs C# Academy zawiera 4 lekcji w sumie.

Jeden dokument na wersję

Gdy API ma kilka wersji, zazwyczaj potrzebny jest oddzielny dokument OpenAPI dla każdej wersji, aby odbiorcy widzieli tylko dotyczące ich endpointy.

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

Dostawca opisów wersji API

Asp.Versioning udostępnia interfejs IApiVersionDescriptionProvider, który wylicza wszystkie wykryte wersje API. Należy przejść po tej kolekcji, aby zarejestrować dokument dla każdej wersji.

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

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

Rejestrowanie dokumentu dla każdej wersji

Należy wywołać AddOpenApi raz dla każdej grupy wersji i nadać każdemu dokumentowi nazwę grupy.

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

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

Filtrowanie endpointów do właściwego dokumentu

Należy użyć transformatora dokumentu lub predykatu ShouldInclude, aby każdy dokument zawierał wyłącznie endpointy swojej wersji, dopasowane na podstawie nazwy grupy.

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

Mapowanie dokumentów

MapOpenApi z domyślnym wzorcem udostępnia każdy nazwany dokument pod adresem /openapi/{documentName}.json.

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

Ustawianie informacji dla poszczególnych dokumentów

Każdemu dokumentowi wersji należy nadać własny tytuł i wersję w transformatorze, aby dokumentacja zawierała wystarczające informacje o sobie.

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

Oznaczanie wycofanych wersji w dokumentacji

Jeśli wersja jest wycofywana, należy umieścić tę informację w opisie dokumentu, aby odbiorcy zobaczyli ostrzeżenie w interfejsie użytkownika.

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

Zastępowanie wersji w adresach URL

SubstituteApiVersionInUrl = true zastępuje token trasy {version:apiVersion} konkretną wersją, na przykład v1, w dokumencie, dzięki czemu ścieżki są czytelniejsze.

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

Karta interfejsu dla każdej wersji

Większość przeglądarek może wyświetlać listę rozwijaną ze wszystkimi dokumentami. Interfejs użytkownika należy skonfigurować tak, aby wskazywał plik JSON każdej wersji.

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

Dokumentowanie kształtów żądań i odpowiedzi

Ponieważ w wersji v2 mogą zmienić się obiekty DTO, każda wersja powinna mieć własne typy DTO. OpenAPI automatycznie wygeneruje wtedy odrębne schematy dla poszczególnych dokumentów.

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

Połączenie wszystkich elementów

Pełny przepływ wygląda następująco: należy skonfigurować wersjonowanie i API Explorer, zarejestrować jeden dokument OpenApi dla każdej wersji wraz z filtrem, zmapować dokumenty i wskazać każdy z nich w interfejsie użytkownika.

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

Szybkie sprawdzenie

Należy sprawdzić, jak tworzone są dokumenty wersjonowanych interfejsów API.

Podsumowanie

Udokumentowano wersjonowane interfejsy API:

Dla każdej wersji zarejestrowano jeden nazwany dokument OpenAPI za pomocą AddOpenApi("vN").
IApiVersionDescriptionProvider wylicza wersje, a ShouldInclude filtruje endpointy.
SubstituteApiVersionInUrl wyświetla ścieżki z konkretnymi wersjami.
Wskazanie każdego dokumentu w interfejsie użytkownika zapewnia widok osobny dla każdej wersji.

To kończy kurs dotyczący wersjonowania i OpenAPI.

Często zadawane pytania

Czy lekcja „Dokumentowanie wersjonowanych API” jest bezpłatna?

Tak — pełny tekst „Dokumentowanie wersjonowanych API” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu C# Academy, przejdź na CoddyKit PRO. Kurs C# Academy zawiera 4 lekcji w sumie.

Co nauczysz się w „Dokumentowanie wersjonowanych API”?

Udostępniaj dokumentację dla wielu wersji API. Ćwiczysz C# Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć C# Academy?

Nie wymagamy żadnego doświadczenia. C# Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 4 z 4.

Ile czasu zajmuje lekcja „Dokumentowanie wersjonowanych API”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji C# Academy?

Tak. Każda lekcja C# Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

← Powrót do C# Academy