4 opcje zastępujące Swagger w interfejsach API .NET 9

Konfiguracja standardowego projektu API

Tim zaczyna od stworzenia minimalnego projektu API w Visual Studio, wybierając standardowy szablon ASP.NET Core Web API.

Podkreśla, aby zaznaczyć opcję dodania wsparcia OpenAPI, co zapewnia, że Twój projekt zawiera niezbędne generowanie dokumentu OpenAPI przez plik JSON.

Gdy projekt działa, Tim przechodzi do domyślnego adresu URL dokumentu OpenAPI (np. /swagger/v1/swagger.json), aby zobaczyć surowe specyfikacje OpenAPI. Ten plik zawiera zorganizowane metadane na temat punktów końcowych API, w tym obsługiwane czasowniki, takie jak GET, POST i DELETE.

Mimo że działa, Tim zauważa, że przeglądanie surowego dokumentu OpenAPI nie jest przyjazne dla użytkownika. Aby zapewnić lepszy interfejs dokumentacji internetowej, przechodzi do przedstawienia czterech zewnętrznych narzędzi, które poprawiają doświadczenia programistów i konsumentów.

Opcja 1: Swagger UI - Znane środowisko

Swagger UI nadal jest bardzo popularnym narzędziem, chociaż nie jest już domyślnie dołączane. Tim demonstruje, jak przywrócić je za pomocą wymagańego pakietu NuGet dotnet: Swashbuckle.AspNetCore.SwaggerUI.

Po skonfigurowaniu Swagger UI w nowym projekcie, o 9:43, konfiguruje pośrednictwo za pomocą uproszczonej składni i ustawia adres URL uruchamiania na /swagger. Ten interfejs użytkownika zapewnia przyjazny interfejs dokumentacji API, w którym programiści mogą przeglądać końcówki, rozumieć parametry żądania i testować je w przeglądarce.

Chociaż Swagger UI jest teraz narzędziem zewnętrznym, nadal wspiera specyfikacje OpenAPI i pozostaje jednym z najlepszych wyborów do podstawowych potrzeb dokumentacyjnych podczas rozwoju.

Opcja 2: ReDoc - Czysta, tylko do odczytu dokumentacja API

Drugim narzędziem Tima jest ReDoc, które przekształca dokument OpenAPI w wypolerowaną, tylko do odczytu stronę HTML. Po dodaniu pakietu OpenAPI Swashbuckle.AspNetCore.ReDoc, mapuje dokumentację na /api/docs.

W przeciwieństwie do Swagger UI, ReDoc nie pozwala na testowanie punktów końcowych. Jednak wyróżnia się jako interfejs dokumentacji internetowej odpowiedni dla użytkowników zewnętrznych i klientów. Jeśli skupiasz się wyłącznie na definiowaniu REST API i wyświetlaniu zorganizowanej dokumentacji, ReDoc jest doskonałym wyborem.

Warto zauważyć, że ReDoc automatycznie generuje treść na podstawie dostarczonych specyfikacji OpenAPI, obejmując oczekiwane odpowiedzi, parametry i typy danych. Jest to zgodne z projektami, które priorytetowo traktują zoptymalizowaną wbudowaną obsługę dokumentacji nad interaktywnością.

Opcja 3: NSwag - Dokumentacja + Generowanie kodu

Następnie Tim zagłębia się w NSwag, elastyczne i bogate w funkcje narzędzie, które robi więcej niż tylko dokumentację API - może również generować kod dla klientów w różnych językach, takich jak C#, TypeScript i inne. Po zainstalowaniu pakietu NuGet NSwag.AspNetCore, konfiguruje interfejs podobny do Swagger, mapując go na ten sam punkt końcowy JSON.

Tim wyjaśnia, że NSwag obsługuje zarówno specyfikacje Swagger, jak i standardy OpenAPI, pozwalając programistom wybrać preferowany format. Chociaż interfejs może wyglądać podobnie do Swagger, to zewnętrzne biblioteki narzędziowe i zaawansowane funkcje (jak automatyczne tworzenie klienta) sprawiają, że NSwag błyszczy.

Wskazuje, że zdolność NSwag do generowania kodu jest pomocna w redukowaniu ręcznego wysiłku przy integracji z API, zwłaszcza w projektach obejmujących wiele serwisów lub narzędzi zewnętrznych. To potężne rozwiązanie dla zespołów budujących solidną komunikację klient-serwer.

Opcja 4: Scałer - Ulubiona Tima do testowania API

Tim przedstawia Scałer UI jako swojego osobistego faworyta spośród wszystkich opcji, opisując go jako mieszankę Postman i dokumentacji w przeglądarce. Po dodaniu pakietu Scałer.AspNetCore, wystarczy jedna linia kodu (app.MapScałerApiReference()), aby umożliwić interfejs.

Scałer wspiera pełną interaktywność, w tym wykonywanie żądań z parametrami zapytania, nagłówkami i ciasteczkami. Co go wyróżnia, to natychmiastowe sprzężenie zwrotne - zwraca czas odpowiedzi, nagłówki i rezultaty ładunku natychmiast.

Wyjątkową cechą Scałer jest zdolność do generowania poleceń curl i fragmentów kodu klienta dla różnych języków (PHP, Node, Python, C# poprzez HttpClient i RestSharp). Tim uważa to za szczególnie użyteczne do szybkiego kopiowania i wklejania wywołań API podczas rozwoju.

Scałer pozwala również na przełączanie pomiędzy trybami jasnym i ciemnym, czyniąc go przyjazną dla użytkownika platformą dokumentacji API z miejscem na dalsze ulepszenia. Jako platforma API o otwartym kodzie źródłowym, Scałer nadal się rozwija z aktywnym utrzymaniem i dużym zainteresowaniem społeczności.

Końcowe myśli: Opcje dają elastyczność

W ostatnich minutach wideo, Tim podkreśla, że usunięcie Swagger UI z szablonów web .NET może wydawać się krokiem wstecz, ale jest to okazja do przyjęcia nowoczesnych, bardziej dostosowanych rozwiązań. Ta zmiana jest zgodna z szybkiymi cyklami wydawniczymi Microsoft, gdzie funkcje stają się bardziej modułowe i skupione.

Wsparcie OpenAPI teraz działa bardziej jako wsparcie pierwszoklasowe, a nie jako sztywna, natywna implementacja. Możesz swobodnie mieszać i dopasowywać narzędzia w zależności od potrzeb projektu - czy to interaktywne testowanie za pomocą Scałer, generowanie kodu klienta z NSwag, czy czyste wyjście z ReDoc.

Tim zachęca programistów do eksplorowania tych narzędzi, sprawdzenia, które pasują do ich przepływu pracy, a nawet użycia wielu interfejsów dla różnych środowisk (np. jeden dla rozwoju i inny dla publicznej dokumentacji). Fakt, że wszystkie te opcje wspierają specyfikacje OpenAPI i Swagger, oznacza, że nie jesteś przypisany do jednego dostawcy lub przepływu pracy.

Wnioski

Dzięki usunięciu Swagger UI jako domyślnego w .NET 9, programiści mają teraz swobodę wyboru najlepszego narzędzia do swoich potrzeb dokumentacji OpenAPI. Niezależnie czy dokumentujesz API HTTP, obsługujesz narzędzia zewnętrzne, czy wspierasz wewnętrzny rozwój, istnieje rozwiązanie, które zgadza się z Twoimi celami.

Dzięki narzędziom takim jak Swagger UI, ReDoc, NSwag i Scałer, dokumentówanie i testowanie API nigdy nie było bardziej dostosowane do potrzeb lub przyjazne dla programisty. Jak pokazuje nam Tim Corey w swoim wideo, wszystko, czego potrzeba to kilka pakietów, kilka linii kodu i chęć eksploracji narzędzi, które najlepiej służą Twojej aplikacji i zespołowi.