C# · Programowanie

Swagger – interaktywna dokumentacja API

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.

scr1

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.

pet.JPG

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

post.JPG

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

postobj

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

To samo tyczy się zapytania GET:

get.JPG

Formularz dla GET:

getobj.JPG

Wynik dla GET:

getresult.JPG

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

obj

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.

2 myśli na temat “Swagger – interaktywna dokumentacja API

  1. services.AddSwaggerGen(
    c =>
    {
    c.SwaggerDoc(„v1”, new Info { Title = „Title”, Version = „v1” });

    // UseFullTypeNameInSchemaIds replacement for .NET Core
    c.CustomSchemaIds(x => x.FullName);

    c.DescribeAllEnumsAsStrings();
    });

    Polubienie

Skomentuj

Wprowadź swoje dane lub kliknij jedną z tych ikon, aby się zalogować:

Logo WordPress.com

Komentujesz korzystając z konta WordPress.com. Wyloguj /  Zmień )

Zdjęcie na Google+

Komentujesz korzystając z konta Google+. Wyloguj /  Zmień )

Zdjęcie z Twittera

Komentujesz korzystając z konta Twitter. Wyloguj /  Zmień )

Zdjęcie na Facebooku

Komentujesz korzystając z konta Facebook. Wyloguj /  Zmień )

Connecting to %s