Dodanie interfejsu Swagger UI do .NET Aspire na Linuxie

Instalacja pakietu Swashbuckle NuGet

[0:38 - 1:35] Tim otwiera projekt Tiny Ticket w VS Code i nawigując do serwisu API's Program.cs. API ma już zdefiniowany punkt końcowy GET /api/tickets z poprzedniego odcinka, ale wymagało to ręcznego skonstruowania URL. Aby dodać właściwy interfejs testowy, pierwszym krokiem jest zainstalowanie pakietu Swagger UI.

Kliknij prawym przyciskiem myszy projekt API, wybierz "Dodaj pakiet NuGet" i wyszukaj Swashbuckle.AspNetCore.SwaggerUI. Tim instaluje najnowszą wersję (10.1.7 w momencie nagrania). Po instalacji referencja do pakietu pojawia się w pliku projektowym. Inne zależności nie są potrzebne, ponieważ projekt już zawiera wsparcie OpenAPI poprzez domyślną konfigurację serwisu Aspire.

// Verify the package was added to the .csproj
// <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.1.7" />

// Verify the package was added to the .csproj
// <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.1.7" />

Configuring Swagger UI in Program.cs

[1:35 - 3:12] Z zainstalowanym pakietem, konfiguracja trafia do wyłącznie rozwojowego bloku Program.cs. Projekt ma już zarejestrowane app.MapOpenApi(), które generuje plik specyfikacji OpenAPI w czasie wykonywania. Swagger UI musi jedynie wiedzieć, gdzie ten plik się znajduje i jak nazwać grupę punktów końcowych.

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

    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "Ticket App API v1");
    });
}

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

    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "Ticket App API v1");
    });
}

Wywołanie SwaggerEndpoint wskazuje na specyfikację OpenAPI, którą .NET generuje automatycznie. Drugim parametrem jest nazwa wyświetlania, która pojawia się w rozwijanym menu Swagger UI. Tim podkreśla, że te trzy linie są całym ustawieniem Swaggera. Można dodać więcej konfiguracji, aby dostosować interfejs użytkownika, grupować endpointy lub dodać nagłówki uwierzytelniania, ale dla narzędzia testowego w rozwoju, domyślne ustawienia są wystarczające.

Jedna rzecz, którą warto zauważyć: od .NET 9, nowe projekty API nie zawierają Swaggera domyślnie. Microsoft oddzielił te kwestie, dostarczając OpenAPI jako standard i pozwalając deweloperom na wybór preferowanej warstwy interfejsu użytkownika. Swagger, Scalar i inne narzędzia wszystkie konsumują ten sam plik specyfikacji OpenAPI, więc nie jesteś ograniczony do żadnego konkretnego widza.

Uruchamianie i weryfikacja interfejsu Swaggera

[3:12 - 6:07] Po zapisaniu, Tim uruchamia projekt przez panel Run and Debug. Gdy deska rozdzielcza Aspire ładuje się i serwis API jest uruchomiony, nawigując do URL API i dodaje /swagger do ścieżki.

Swagger UI ładuje się z etykietą "Ticket App API v1" i wyświetla dostępne endpointy. Główny punkt końcowy (/) zwraca prostą wiadomość o stanie, a /api/tickets zwraca dane biletów z bazy danych.

Tim klika "Try it out" na głównym endpoint i wykonuje go. Odpowiedź wraca z odpowiedzią 200 i komunikatem potwierdzenia. Następnie przechodzi do punktu końcowego /api/tickets i naciska wykonanie, co jest początkiem rozwiązywania problemów.

Pierwsza próba kończy się niepowodzeniem z błędem połączenia: "Wystąpił błąd sieciowy lub specyficzny dla instancji podczas nawiązywania połączenia z serwerem SQL." Kontener bazy danych nie został uruchomiony po restarcie maszyny. Tim otwiera Portainera, znajduje kontener Docker serwera SQL i uruchamia go. Po zakończeniu inicjalizacji kontenera, wraca do Swaggera i ponownie wykonuje żądanie. Tym razem odpowiedź wraca z odpowiedzią 200 z trzema testowymi biletami przechowywanymi w bazie danych.

Ta sekwencja to praktyczne przypomnienie, że testy integracyjne przeciwko rzeczywistej infrastrukturze ujawnią problemy, które testy jednostkowe i dane testowe nie mogą wyświetlić. Kontener bazodanowy nie jest ustawiony do automatycznego uruchamiania przy starcie, co oznacza, że pierwszy wywoływanie API po restarcie zakończy się niepowodzeniem, chyba że najpierw zweryfikujesz stan kontenera.

Co będzie dalej: Endpointy CRUD

[6:07 - 7:20] Tim previewuje nadchodzące odcinki w serii. API Tiny Ticket obecnie ma tylko punkt końcowy GET /api/tickets, który odwzorowuje procedurę składowaną spTickets_GetAll. Pozostałe procedury składowane w bazie danych (Pobierz według ID, Wstaw, Aktualizuj, Usuń) każdy potrzebuje odpowiedniego punktu końcowego API z prawidłową metodą HTTP: GET dla pobierania, POST dla tworzenia, PUT dla aktualizacji i DELETE dla usunięcia.

Zaznacza, że każdy endpoint podąża za tym samym wzorem i jest prosty do wdrożenia, ale nadchodzące wideo pojedynczo omówią je tak, aby każdy kawałek był łatwy do odniesienia oddzielnie. Decyzja o podziale serii na niewielkie, skupione odcinki oznacza, że możesz bezpośrednio przeskoczyć do potrzebnego typu endpointu bez przeskakiwania przez dłuższe wideo.

Wnioski

[7:20 - 7:24] Dodanie Swagger UI do projektu .NET Aspire na Linux wymaga jednego pakietu NuGet i trzech linii konfiguracji w Program.cs. Plik specyfikacji OpenAPI jest już generowany przez domyślną konfigurację serwisu Aspire, więc Swagger potrzebuje tylko wskazówki do tego pliku i nazwę wyświetlania. Od tego momentu każdy endpoint w API jest testowalny przez przeglądarkę bez potrzeby budowania oddzielnego klienta.

Problem z połączeniem do bazy danych spotkany przez Tima po restarcie wzmacnia praktyczny punkt: kiedy stos rozwoju zawiera kontenery, upewnij się, że są uruchomione przed testowaniem endpointów API. Swagger daje szybki obieg informacji zwrotnej dla tej weryfikacji.

Nawigacja po serii: Ten artykuł jest częścią serii C# na Linux budującą aplikację Tiny Ticket. Poprzednie: Ustawianie Aspire na Linux. Następne: Dodanie Endpointu "Get By ID".

Przykładowa wskazówka: Jeśli preferujesz inny widok OpenAPI zamiast Swagger, zainstaluj pakiet taki jak Scalar lub RapiDoc i skieruj go na ten sam punkt końcowy /openapi/v1.json. Plik specyfikacji jest agnostyczny dla UI, więc możesz zmieniać widzów bez zmiany konfiguracji API.

Obejrzyj pełne wideo na jego kanale YouTube tutaj i uzyskaj więcej wglądów na budowę API w serii C# na Linux.