Dokumentowanie internetowego interfejsu API platformy ASP.NET Core przy użyciu narzędzi Swagger

  • 5 min

Interfejs API może mieć doskonałą wartość, ale nie może uzyskać trakcji, chyba że deweloperzy wiedzą, jak z niego korzystać. Deweloperzy chcą zintegrować interfejs API tak szybko, jak to możliwe. Dobra dokumentacja interfejsu API pomaga deweloperowi poznać możliwości interfejsu API i sposób jego używania, dzięki czemu integracja jest efektywniejsza.

Tradycyjnie całą dokumentację opisującą interfejs API oraz sposób jego używania pisano ręcznie. Teraz mamy standardową specyfikację opisów interfejsów API o nazwie OpenAPI. Interfejs użytkownika struktury Swagger udostępnia narzędzia implementacji i testowania specyfikacji interfejsu OpenAPI dla interfejsów API. Swashbuckle to pakiet typu open source, który zapewnia automatyczne generowanie dokumentów opisu interfejsu OpenAPI bezpośrednio z kontrolerów internetowego interfejsu API przy użyciu odbicia platformy .NET. Pakiet Swashbuckle pomaga zautomatyzować proces opisu, ułatwiając zespołom generowanie, konserwowanie i używanie dokumentacji interfejsu API opartej na protokole OpenAPI. Opisujesz interfejs API i umożliwiasz narzędziom generowanie zaawansowanej dokumentacji.

Co to jest OpenAPI?

OpenAPI to specyfikacja używana do opisywania interfejsów API REST. Jest niezależny od języka i umożliwia opisanie całego interfejsu API, w tym:

  • Dostępne punkty końcowe
  • Parametry operacji
  • Metody uwierzytelniania
  • Informacje kontaktowe i inne

Specyfikacje interfejsów API można pisać w języku YAML lub notacji JSON. Dzięki specyfikacji OpenAPI ludzie i komputery mogą poznawać możliwości interfejsu API bez uzyskiwania dostępu do jego kodu źródłowego.

Co to jest Swagger?

Swagger to zestaw narzędzi typu open source, które pozwalają na pracę ze specyfikacją OpenAPI. Te narzędzia mogą pomóc w projektowaniu, tworzeniu i dokumentowaniu interfejsów API REST. Narzędzie Swagger używa specyfikacji interfejsu API OpenAPI, aby zrozumieć jego strukturę.

Na przykład Swagger UI to narzędzie, które wizualnie przedstawia w przeglądarce dokumentację interfejsu API, dla którego zdefiniowano specyfikację OpenAPI. Narzędzie Swagger Codegen może wygenerować zestawy SDK klientów, korzystając z tej samej specyfikacji OpenAPI.

Co to jest Swashbuckle?

Swashbuckle to implementacja struktury Swagger typu open source używana do generowania dokumentacji struktury Swagger dla interfejsów API platformy .NET Core przy użyciu odbicia platformy .NET.

Pakiet Swashbuckle składa się z trzech głównych składników:

  • Swashbuckle.AspNetCore.Swagger: ten składnik jest modelem obiektów programu Swagger i oprogramowaniem pośredniczącym do uwidaczniania SwaggerDocument obiektów jako punktów końcowych JSON.

  • Swashbuckle.AspNetCore.SwaggerGen: ta biblioteka jest generatorem struktury Swagger, który tworzy SwaggerDocument obiekty bezpośrednio z tras, kontrolerów i modeli. Biblioteka jest zwykle połączona z oprogramowaniem pośredniczącym punktu końcowego programu Swagger w celu automatycznego uwidocznienia kodu JSON programu Swagger.

  • Swashbuckle.AspNetCore.SwaggerUI: ten pakiet jest osadzoną wersją narzędzia Swagger UI. Interpretuje kod JSON programu Swagger w celu tworzenia rozbudowanych, możliwych do dostosowania środowisk na potrzeby opisywania funkcji internetowego interfejsu API. Obejmuje wbudowane kontrolery testów dla metod publicznych.

  • Interfejs wiersza polecenia pakietu Swashbuckle: po zainstalowaniu to narzędzie globalne platformy .NET umożliwia generowanie specyfikacji interfejsu OpenAPI podczas kompilacji/publikowania. Na końcu tego modułu znajduje się link umożliwiający pobranie interfejsu wiersza polecenia pakietu Swashbuckle.

Ponieważ te biblioteki są dodawane do Twojej aplikacji, generują i wizualizują dokumentację interfejsu API z jego najnowszej wersji. Tworzą żywą dokumentację, zawsze zsynchronizowaną z najnowszym kodem.