C# Academy · Lekcja

Generowanie dokumentów OpenAPI

Twórz specyfikacje API w formacie czytelnym maszynowo.

Generowanie dokumentów OpenAPI to bezpłatna lekcja C# Academy na CoddyKit. To lekcja 3 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.

Czym jest OpenAPI?

OpenAPI to standardowy, czytelny maszynowo opis interfejsu HTTP API. Na jego podstawie można generować dokumentację, zestawy SDK klientów i narzędzia do testowania.

.NET 9 ma wbudowane generowanie dokumentów OpenAPI, które w wielu aplikacjach zastępuje starszą zależność Swashbuckle.

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

Pakiet Microsoft.AspNetCore.OpenApi

Wbudowana obsługa znajduje się w pakiecie Microsoft.AspNetCore.OpenApi. W szablonach platformy .NET 9 jest on już uwzględniony jako odwołanie.

dotnet add package Microsoft.AspNetCore.OpenApi

AddOpenApi

Generator dokumentów należy zarejestrować za pomocą AddOpenApi w konfiguracji usług.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

MapOpenApi

MapOpenApi udostępnia wygenerowany dokument za pośrednictwem endpointu. Domyślnie jest on dostępny pod adresem /openapi/v1.json.

var app = builder.Build();

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

app.Run();

Ograniczenie do środowiska deweloperskiego

Często dokument udostępnia się wyłącznie w środowisku deweloperskim, aby uniknąć ujawnienia zakresu API na produkcji.

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

Opisywanie endpointów

Metadane OpenAPI są wzbogacane na podstawie kodu. W przypadku endpointów Minimal APIs należy używać metod WithSummary, WithDescription i WithTags.

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

Dokumentowanie odpowiedzi

Należy zadeklarować typy odpowiedzi i kody stanu, aby dokument zawierał ich dokładny opis.

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

Transformatory dokumentu

Cały dokument — jego tytuł, wersję i serwery — można dostosować za pomocą transformatora dokumentu przekazanego do AddOpenApi.

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

Transformatory operacji

Transformator operacji modyfikuje poszczególne operacje — na przykład dodaje wspólny parametr nagłówka do każdego endpointu.

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

Dodawanie interfejsu użytkownika

Wbudowany generator tworzy dokument JSON, ale nie zapewnia interfejsu użytkownika. Należy połączyć go z przeglądarką, taką jak Scalar lub Swagger UI.

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

Generowanie podczas kompilacji

Plik OpenAPI można wygenerować podczas kompilacji, bez uruchamiania serwera, za pomocą narzędzi Microsoft.Extensions.ApiDescription.Server. Jest to przydatne przy generowaniu klientów w ramach CI.

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

Szybkie sprawdzenie

Należy sprawdzić znajomość podstaw OpenAPI w .NET 9.

Podsumowanie

Wygenerowano dokumenty OpenAPI:

AddOpenApi() rejestruje generator, a MapOpenApi() udostępnia kod JSON.
Endpointy można wzbogacać za pomocą WithSummary, Produces i tagów.
Transformatory dokumentów i operacji dostosowują dane wyjściowe.
Połączenie ze Scalar lub Swagger UI zapewnia interaktywny widok.

Następnie: dokumentowanie wersjonowanych interfejsów API.

Często zadawane pytania

Czy lekcja „Generowanie dokumentów OpenAPI” jest bezpłatna?

Tak — pełny tekst „Generowanie dokumentów OpenAPI” 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 „Generowanie dokumentów OpenAPI”?

Twórz specyfikacje API w formacie czytelnym maszynowo. Ć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 3 z 4.

Ile czasu zajmuje lekcja „Generowanie dokumentów OpenAPI”?

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