.NET Conf

Ekosystem .NET przeszedł znaczącą transformację w zakresie dokumentacji API, szczególnie w kontekście specyfikacji OpenAPI. Microsoft odchodzi od rozwiązań zewnętrznych, takich jak Swashbuckle, na rzecz natywnej obsługi OpenAPI w .NET 9. Alternatywy, np. NSwag, nadal oferują zaawansowane łańcuchy narzędzi do generowania dokumentacji i kodu klienta. W ekosystemie dostępne są różne podejścia: od narzędzi typu „swagger tofile”, integracji z MSBuild, aż po nowoczesne rozwiązania jak Scalar. Te zmiany wpisują się w branżowy trend standaryzacji dokumentacji API, poprawiając kompatybilność oraz ułatwiając utrzymanie narzędzi.

Spis treści [odkryj]

Podstawy – OpenAPI w ekosystemie .NET

OpenAPI to standard w dokumentacji usług REST, zapewniający ustrukturyzowany opis endpointów, formatów żądań, odpowiedzi oraz autoryzacji. Standaryzacja ułatwia deweloperom korzystanie z API, wspiera współpracę i budowę solidniejszych aplikacji. Dzięki specyfikacji powstało wiele narzędzi:

  • swagger UI,
  • kiota (generator klientów),
  • ReDoc,
  • inne middleware do pracy z dokumentacją.

OpenAPI wspiera też integrację AI, generowanie testów czy automatyczne tworzenie klientów na różne platformy.

Na początku ekosystem .NET opierał się na zewnętrznych bibliotekach do generowania dokumentacji OpenAPI. Największą popularność zdobyło Swashbuckle.AspNetCore, które oferuje middleware oraz Swagger UI. Jednak rozwiązania zewnętrzne niosły ograniczenia związane z kompatybilnością i utrzymaniem.

Kolejnym etapem rozwoju był NSwag, łączący generowanie specyfikacji OpenAPI i kodu klienckiego. Dzięki temu unika problemów zgodności, obsługuje zaawansowane cechy API i radzi sobie z referencjami, które nie są jednoznacznie opisane w samym OpenAPI.

Swashbuckle – klasyczne generowanie OpenAPI

Swashbuckle.AspNetCore przez lata służyło jako domyślne narzędzie OpenAPI w ASP.NET Core. Składa się z trzech głównych komponentów:

  • Swashbuckle.AspNetCore.Swagger – udostępnia model i middleware publikujący dokument JSON;
  • Swashbuckle.AspNetCore.SwaggerGen – generator analizujący kontrolery i automatycznie tworzący dokumentację OpenAPI;
  • Swashbuckle.AspNetCore.SwaggerUI – interaktywny interfejs UI umożliwiający testowanie metod API.

Proces integracji jest prosty: pobierz NuGet dotnet add package Swashbuckle.AspNetCore, skonfiguruj generator w ConfigureServices, a endpointy odpowiednio otaguj (np. [HttpPost], [FromBody]). Middleware aktywujesz poprzez app.UseSwagger() oraz app.UseSwaggerUI(). Uzyskujesz wtedy dostęp do dokumentacji pod /swagger/v1/swagger.json oraz UI pod /swagger.

W .NET 9 Swashbuckle nie jest już wspierane – Microsoft zachęca do natywnych narzędzi, eliminując wieloletnie problemy kompatybilności.

NSwag – kompleksowe narzędzia do OpenAPI

NSwag oferuje rozbudowany ekosystem narzędzi Swagger/OpenAPI, w tym generatory klientów C#, TypeScript, Angular i innych. Dzięki NJsonSchema zapewnia silne typowanie i generowanie klas po stronie serwera i klienta. W skład NSwag wchodzą:

  • NSwagStudio – narzędzie GUI do konfiguracji generowania specyfikacji i klientów;
  • narzędzia CLI dla Windows, Mac i Linux;
  • pakiety NPM wspierające frontend;
  • integracja z MSBuild i obsługa referencji usługowych.

Integracja z ASP.NET Core sprowadza się do kilku linii kodu: rejestrujesz serwisy services.AddOpenApiDocument() (OpenAPI v3) lub services.AddSwaggerDocument() (Swagger v2), a następnie aktywujesz odpowiedni middleware app.UseOpenApi(), app.UseSwaggerUi() lub app.UseReDoc().

NSwag automatycznie generuje klientów C# na podstawie specyfikacji OpenAPI, minimalizując błędy integracji. To w pełni zautomatyzowane i może współpracować z MSBuild (NSwag.MSBuild).

Możliwość przekazywania zmiennych środowiskowych i integracji z pipeline CI/CD pozwala elastycznie automatyzować cały proces generowania dokumentacji i klientów.

Generowanie OpenAPI „na etapie budowania” – swagger tofile

Polecenie swagger tofile pozwala generować dokumentację na etapie kompilacji, co daje dodatkowe korzyści:

  • wersjonowanie i recenzję specyfikacji w systemach kontroli kodu,
  • integrację z testami, gdzie specyfikacja jest kontraktem API,
  • udostępnianie statycznych plików dokumentacji bez konieczności uruchamiania aplikacji.

Wymagana jest instalacja Swashbuckle.AspNetCore.Cli: najlepiej lokalnie przez manifest narzędzi. Uruchamiasz:

dotnet swagger tofile [ścieżka-do-assembly] [nazwa-dokumentu]

Częstym problemem są błędy związane z niezgodnością wersji SDK i frameworka. Najlepiej rozwiązać to przez dodanie global.json, który wymusza odpowiednie SDK.

Od .NET 8/9 Microsoft wskazuje, że Swashbuckle nie wspiera już generowania dokumentacji w czasie buildu. Możliwe są obejścia, np. DOTNET_ROLL_FORWARD=LatestMajor, ale to rozwiązania tymczasowe.

Zmiana strategii Microsoftu od .NET 9

Microsoft odchodzi od Swashbuckle i stawia na natywną obsługę OpenAPI w .NET 9. Pozwala to wykorzystać nowoczesny stack: System.Text.Json, kompilację AoT i Minimal APIs.

Natywna obsługa pozwala generować dokumenty OpenAPI zarówno w runtime, jak i build-time. Integracja atrybutów i rozszerzeń umożliwia wzbogacenie opisów, walidacje, przykłady oraz generowanie wielu dokumentów – co jest istotne dla rozbudowanych ekosystemów.

Podstawą jest Microsoft.Extensions.ApiDescription.Server, pozwalająca zapisywać dokumenty OpenAPI w katalogu obj lub wskazanym przez OpenApiDocumentsDirectory.

Framework uruchamia aplikację w specjalnym trybie, by zebrać pełne metadane runtime – często wymaga to warunkowego wyłączenia fragmentów kodu (np. połączeń do baz danych).

Pozostawienie Swagger UI poza szablonem pozwala korzystać z nowoczesnych alternatyw – jak Scalar, który zapewnia lepszy wygląd, personalizację i generowanie klientów.

Najczęstsze trudności i rozwiązywanie problemów

Programiści regularnie napotykają powtarzalne wyzwania podczas implementacji OpenAPI w .NET:

  • kompatybilność wersji – najczęściej dotyczy „swagger tofile”, konieczny global.json;
  • instalacja narzędzi – lokalna instalacja przez manifest umożliwia lepszą kontrolę, ale wymaga używania dotnet tool restore po przeniesieniu projektu;
  • integracja z budowaniem – należy pilnować poprawnej kolejności zadań i ścieżek, typowe są błędy z brakiem plików lub niewłaściwymi ścieżkami;
  • CI/CD i DevOps – wymaga odpowiedniej konfiguracji agentów i przesyłania artefaktów;
  • specyficzna konfiguracja środowiska – często generowanie dokumentacji wymaga uproszczonej inicjalizacji, natywna obsługa .NET 9 pozwala wykryć tryb generowania i pominąć fragmenty kodu;
  • rejestracja zbędnych serwisów – np. niepotrzebne contexty bazodanowe rejestrowane podczas generowania dokumentacji mogą powodować błędy.

Nowoczesne alternatywy oraz perspektywy

Narzędzia nowej generacji jak Scalar zrewolucjonizowały sposób prezentowania dokumentacji w .NET. Scalar, zbierający popularność (ponad 10 000 gwiazdek na GitHub), pozwala na pełną personalizację interfejsu – od tytułów po motywy graficzne.

Integracja Scalar z .NET 9 Web API jest uproszczona: instalujesz Scalar.AspNetCore z NuGet, konfigurujesz jedną linią w Program.cs. Narzędzie korzysta z natywnie wygenerowanej dokumentacji i prezentuje ją w nowoczesnym UI.

Do generowania klientów HTTP z linii poleceń służy Microsoft.dotnet-openapi, a nowoczesne pipeline’y coraz częściej wykorzystują liblab do automatycznej budowy SDK i testowania zmian API.

Przyszłość należeć będzie do głębokiej integracji z AI/LLM, automatycznych detekcji błędów i generowania testów/przykładów zgodnie z dobrymi praktykami. Microsoft stawia na oficjalne narzędzia, by poprawić bezpieczeństwo i przewidywalność wdrożeń.

Wzorce integracji oraz najlepsze praktyki

Prawidłowa dokumentacja OpenAPI w .NET wymaga przemyślanej integracji na każdym etapie:

  • generowanie runtime – szybki podgląd i aktualizacje, ale ryzyko ujawnienia informacji w produkcji;
  • generowanie build-time – pełna kontrola nad udostępnianiem, testowaniem i wersjonowaniem, wymaga zmian inicjalizacji;
  • integracja z MSBuild – dbałość o kolejność zadań i obsługę błędów;
  • zarządzanie narzędziami – lokalna instalacja daje powtarzalność, ale wymaga przywracania w nowych środowiskach;
  • kontrola wersji – konieczne strategie migracji do natywnej obsługi (np. .NET 9), szczególnie w starszych projektach;
  • standaryzacja jakości – walidacja automatyczna, standardy opisów i przykłady są kluczowe, zwłaszcza w dużych organizacjach.

Wydajność oraz skalowalność

Narzędzia OpenAPI wpływają na czas startu, zużycie pamięci i wydajność całego ekosystemu.

  • generowanie runtime – obciążenie przez reflection i analizę metadanych, spowalnia start w dużych projektach, utrudnia efektywność serverless i kontenerów;
  • zużycie pamięci – runtime trzyma struktury metadanych cały czas, build-time ogranicza wpływ do fazy buildu;
  • kompilacja AoT – natywna obsługa zapewnia wysoką wydajność dla Minimal APIs;
  • cache’owanie – zarówno runtime, jak i build-time mogą korzystać z cache dla optymalizacji;
  • skalowalność – agregacja dokumentacji wielu mikroserwisów i optymalizacja pod kontenery i deploymenty;
  • optymalizacja sieciowa – rozbudowane specyfikacje mogą zwiększać obciążenie oraz czas ładowania po stronie klienta, szczególnie na urządzeniach mobilnych.

Zalecane jest testowanie wydajności przy różnych ustawieniach OpenAPI, by precyzyjnie ocenić wpływ na kluczowe metryki.

Bezpieczeństwo i zgodność

Generowanie dokumentacji OpenAPI wiąże się z ryzykiem bezpieczeństwa wykraczającym poza samą dokumentację. Najważniejsze aspekty obejmują:

  • ujawnianie szczegółów architektury – specyfikacje mogą zdradzać wewnętrzne parametry i logiczne szczegóły;
  • rekonesans atakującego – szczegółowa dokumentacja zwiększa powierzchnię analizy API;
  • osobne wersje dokumentacji dla użytkowników zewnętrznych i wewnętrznych;
  • wymóg autoryzacji – ogranicz dostęp do dokumentacji (Basic Auth, VPN, restrykcje IP);
  • build-time/offline – dokumentacja i narzędzia nie są wdrażane w produkcji, minimalizując pole ataku;
  • CI/CD – przechowywanie tajnych danych, audyt zmian i ścisłe logowanie;
  • zgodność branżowa – finanse, zdrowie, administracja wymagają pełnej audytowalności i zatwierdzania zmian dokumentacji;
  • RODO/GDPR/CCPA – sprawdzaj, czy specyfikacja nie zawiera wrażliwych danych w przykładach/payloadach;
  • kontrola zmian – audyt i kontrola dostępu do modyfikacji specyfikacji będących kontraktem między zespołami lub kontrahentami;
  • użycie oficjalnych narzędzi Microsoft – ogranicza zależności od zewnętrznych rozwiązań, zapewniając szybkie reagowanie na zagrożenia.

Regularny audyt i automatyzacja kontroli są niezbędne, by minimalizować ryzyko ujawnienia wrażliwych informacji w publikowanych dokumentacjach API.