Ten post został ostatnio edytowany przez QWERTYU w dniu 12.04.2019 o 14:24
WprowadzeniePo użyciu asp.net Core do tworzenia API, pisanie dokumentacji API musi być dla programistów bolesnym zadaniem, ale dokumentacja musi być napisana, a jeśli nie ma konkretnych wymagań dotyczących formatu dokumentacji, ostateczna dokumentacja zależy całkowicie od nastroju dewelopera. Albo być bardziej szczegółowym albo prostszym. Czy istnieje szybki i efektywny sposób na budowanie dokumentacji API? Odpowiedź brzmi: tak, Swagger to jedno z najpopularniejszych narzędzi do generowania dokumentacji w REST API!
Dlaczego warto używać Swagger jako narzędzia do generowania dokumentacji REST API- Swagger może wygenerować interaktywną konsolę API, dzięki której deweloperzy mogą szybko uczyć się i eksperymentować z API.
- Swagger może generować kod SDK klienta dla implementacji na różnych platformach.
- Pliki Swagger mogą być automatycznie generowane na podstawie komentarzy kodu na wielu różnych platformach.
- Swagger ma silną społeczność z wieloma silnymi współtwórcami.
Jak używać Swagger do generowania dokumentacji API w asp.net core?- Swashbuckle.AspNetCore to projekt open-source, który generuje dokumentację Swagger dla ASP.NET Core Web API.
- NSwag to kolejny projekt open-source integrujący interfejs Swagger UI lub ReDoc z ASP.NET Core Web API. Zapewnia możliwość generowania kodu klienta w C# i TypeScript dla API.
Poniżej znajduje się przykład Swashbuckle.AspNetCoreJakie są elementy Szermierza?- Swashbuckle.AspNetCore.Swagger: Udostępnia obiekt SwaggerDocument jako model obiektowy Swagger i oprogramowanie pośredniczące dla punktów końcowych JSON.
- Swashbuckle.AspNetCore.SwaggerGen: Generator Swagger, który generuje obiekty SwaggerDocument bezpośrednio z tras, kontrolerów i modeli. Często jest łączony z programem pośredniczącym Swagger endpoint, aby automatycznie udostępniać Swagger JSON.
- Swashbuckle.AspNetCore.SwaggerUI: Osadzona wersja narzędzia UI Swagger. Interpretuje Swagger JSON, tworząc konfigurowalne, bogate doświadczenia opisujące funkcjonalność Web API. Zawiera wbudowane narzędzia testowe dla powszechnych metod.
Jak zainstalować Swashbuckle z vs2017?
Pierwszy sposób: instalacja z okna konsoli Menedżera Pakietów
- Przejdź do widoków > innych konsoli menedżera pakietów Windows >
- Przejdź do katalogu zawierającego plik TodoApi.csproj
- Proszę wykonać następujące polecenie · Install-Package Swashbuckle.AspNetCore
-
Drugi sposób: Z okna Zarządzanie pakietami NuGet:- Kliknij prawym przyciskiem myszy na projekt w Eksploratorze rozwiązań, > Zarządzaj pakietami NuGet
- Ustaw źródło pakietu na nuget.org
- Wpisz w pole wyszukiwania "Swashbuckle.AspNetCore"
- Wybierz pakiet Swashbuckle.AspNetCore z zakładki Przeglądaj i kliknij Install
-
Dodaj i skonfiguruj middleware SwaggerNajpierw wprowadź przestrzeń nazw: Dodaj generator Swagger do kolekcji usług w metodzie Startup.ConfigureServices: przyStartup.Configuremetoda, włączenie middleware do obsługi wygenerowanego dokumentu JSON oraz interfejsu Swagger:
Uruchom aplikację i przejdź do niejhttps://localhost:<port>/swagger/v1/swagger.json。 Powstała dokumentacja opisująca punkt końcowy jest wyświetlana w formacie JSON w następujący sposób.
Dostępnehttps://localhost:<port>/pewność siebieZnajdź interfejs Swagger. Przeglądaj dokumentację API przez interfejs Swagger, jak pokazano poniżej.
Aby zastosować pierwiastek (http://localhost:<port>/) aby udostępnić interfejs Swagger, proszę wpisaćPrzedtekst trasyWłasność jest ustawiona na pusty ciąg znaków:
Zaawansowane wykorzystanie Swagger (personalizacja i rozszerzenia)Użyj Swagger, aby dodać informacje wyjaśniające do dokumentacji APINastępujące operacje konfiguracyjne są wykonywane w metodzie AddSwaggerGen, która dodaje informacje takie jak autor, licencja i opis informacji: Informacje o wersji wyświetlającej interfejs waggera przedstawiono na następującym rysunku: Dodaj komentarze do metod interfejsuNajpierw kliknijmy na API, rozwińmy jak pokazano na poniższym rysunku, czy nie ma komentarzy, jak dodać komentarze? Dodaj komentarze do dokumentu z trwem/jak pokazano na poniższym obrazku, jak pokazano poniżej Następnie uruchom projekt i wróć do swaggerUI, żeby zobaczyć, czy pojawi się komentarz Wciąż się nie pojawił, nie martw się, spójrz w dół! Włączenie adnotacji XMLMożesz włączyć adnotacje XML za pomocą następujących metod: - Kliknij prawym przyciskiem myszy na projekt w Eksploratorze rozwiązań i wybierz Właściwości
- Sprawdź pole pliku XML Document File w sekcji Output na zakładce Build
-
Włączanie adnotacji XML dostarcza informacji do debugowania dla nieudokumentowanych typów i członków typów i członków. Jeśli pojawia się dużo komunikatów ostrzegawczych, na przykład, następująca wiadomość wskazuje na naruszenie kodeksu ostrzegawczego 1591:
A co jeśli masz OCD i chcesz anulować ostrzeżenie? Możesz anulować, jak pokazano na poniższym obrazku
Zwróć uwagę na ścieżkę pliku pliku xml wygenerowanego powyżej,
Nuta: 1. W przypadku systemów Linux lub innych niż Windows nazwy plików i ścieżki są zależne od wielkości liter. Na przykład plik "SwaggerDemo.xml" działa na Windowsie, ale nie na CentOS. 2. Aby uzyskać ścieżkę aplikacji, zaleca się użycie AppContext.BaseDirectory Odbuduj projekt i uruchom projekt, aby zobaczyć, czy pojawią się komentarze Z powyższej operacji można podsumować, że interfejs Swagger wyświetla <summary> wewnętrzny tekst elementów powyższego kodu komentarza jako duże komentarze API! Oczywiście możesz także dodać element uwag do dokumentacji Get how-to. Może uzupełniać <summary> informacje określone w elemencie i zapewnić bardziej niezawodny interfejs użytkownika Swagger. <remarks> Zawartość elementów może zawierać tekst, JSON lub XML. Kod jest następujący: Przetestuj interfejs API za pomocą SwaggerUIDebugujmy interfejs za pomocą SwaggerUI na małym przykładzie
- Kliknij na interfejs API, który trzeba przetestować, a następnie kliknij przycisk "Wypróbuj to" po lewej i prawej stronie Parametry
- Wpisz parametr w polu tekstowym parametru, który pojawia się, jak pokazano na poniższym obrazku, wpisz parametr 2
- Kliknij przycisk Wykonaj, a sformatowana odpowiedź pokazana poniżej pojawi się, jak pokazano na poniższym rysunku
To wszystko na dzisiejszy samouczek o używaniu Swagger do generowania dokumentacji API w ASP.NET Core WebApi. Mam nadzieję, że będzie dla Ciebie pomocne nauczyć się, jak używać Swagger do generowania dokumentacji API w ASP.NET Core! streszczenieTen artykuł zaczyna się od problemu pisania dokumentacji API ręcznie, a następnie prowadzi do Swagger, narzędzia automatycznie generującego dokumentację API! Następnie, za pomocą łatwego do zrozumienia tekstu i obrazków, pokażemy, jak używać SwaggerUI do generowania dokumentacji API w ASP.NET Core WebApi. Na koniec przedstawię kilka zaawansowanych zastosowań Swagger w ASP.NET Core! Mam nadzieję, że pomoże ci to używać Swagger w ASP.NET Core!
| 
Opublikowano 12.04.2019 14:14:46
|
|
|
|
