Masz jakieś API chciałbyś sprawdzić listę swoich endpointów? Swagger to najlepsze narzędzie do tego – do tworzenia interaktywnej dokumentacji API.

Zaczynamy

Wszystkie podstawowe informacje o swaggerze można znaleźć na stronie microsoftu.

Krok 1 – instalacja biblioteki

Po wpisaniu w wyszukiwarkę pakietów nuget słowo „swagger”, pierwsza biblioteka, która sie wyświetla, to Swashbuckle.

Co ważne, swagger działa zarówno dla projektów napisanych w .NET framework oraz .NET Core.

Całą dokumentację można znaleźć na GitHubie biblioteki. Automatycznie tworzy się plik konfiguracyjny SwaggerConfig, w którym można ustawiać różne parametry (np. różne wersje API, autoryzację oraz sam wygląd). Przeważnie Swagger nie wymaga żadnej złożonej konfiguracji. Zwykle instalujesz i działa 😀 Dostępny jest pod stałym adresem your_url/swagger (automatycznie przechodzi do your_url/swagger/ui/index).

Przykład

Przykładową aplikację można znaleźć pod linkiem http://petstore.swagger.io/.

Na początku widać listę endpointów np. dla kontrolera pet.

Po kliknięciu w konkretną metodę można zobaczyć szczegóły np. strukturę obiektu, który ma być wysłany w zapytaniu POST:

Można również kliknąć przycisk po prawej „Try it out”. Otworzy się wtedy formularz z możliwością wypełnienia przykładowego obiektu:

oraz z możliwością wysłania go w zapytaniu POST.

To samo tyczy się zapytania GET:

Formularz dla GET:

Wynik dla GET:

Poza listą endpointów można również wyświetlić strukturę obiektów:

Demo

Chciałam pokazać wykorzystanie w moim własnym projekcie. Na prawdę. Próbowałam. Ale niestety nie udało mi się doprowadzić do tego, żeby zadziałało. Tak nietypowo:

U mnie NIE działa

Może to wina Angulara. A może tego, że to jest MVC, a nie WebAPI. A może po prostu powinnam użyć jakiejś specjalnej konfiguracji. Niestety na ten moment nie znalazłam rozwiązania.