w , ,

FajneFajne ŚwietnieŚwietnie

Swagger UI – przejrzysta wizualizacja zasobów API

Swagger 2 - dokumentowanie API

Co to jest Swagger?

Swagger to zestaw narzędzi, które pomagają programistom projektować, tworzyć, dokumentować i korzystać z usług REST API.

Swagger sprawia, że projektowanie interfejsu API jest znacznie prostrze. Dużo osób utożsamia ten zestaw narzędzi z konkretnym produktem jaki jest Swagger UI. Nie bez przyczyny, gdyż Swagger UI jest genialny w swoich możliwościach i łatwy w zastosowaniu – przez co staje się najbardziej rozpoznawalnym produktem.

Swagger UI

Interfejs Swagger UI pozwala każdemu – zespołowi programistycznego lub użytkownikom aplikacji na wizualizację zasobów API i korzystanie z nich bez konieczności posiadania zewnętrznych aplikacji. Ponadto jest on generowany automatycznie na podstawie specyfikacji OpenAPI.

Jednak kluczową przewagą wykorzystania tego narzędzia jest uzyskanie samoaktualizującej się dokumentacji. Niemniej dla większości programistów męczarnia jest napisanie dokumentacji do API, a problem rośnie za każdym razem jak musimy dokonywać modyfikacji. Niestety utrzymanie dokumentacji jest trudne, często pojawiają się w niej błędy wynikające z niekonsekwencji jej tworzenia lub rozbieżności pomiędzy wersją API a wersją dokumentacji. Dlatego powstał Swagger, który zwalnia programistów z tego problemu 🙂

Swagger UI i Spring Boot

Przedstawiam kroki do zintegrowania aplikacji napisanej z wykorzystaniem Spring Boot i Swagger UI.

Dodanie zależności

Do projektu z API należy dodać dwie zależności. Pierwsza z nich dostarcza możliwości wykorzystania narzędzia w podstawowej wersji, natomiast druga nakładkę graficzną.

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

Przede wszystkim domyślna dokumentacja jest generowana w postaci JSON i dla potrzeby jej wygenerowania wystarczy pierwsza zależność.

Zdefiniowanie klasy konfiguracyjnej

Klasa konfiguracyjna musi zawierać dwie adnotacje:

  • @Configuration – stanowi informacje dla Spring, że jest to klasa zawierająca konfiguracje
  • @EnableSwagger2 – wskazuje, że obsługa tego narzędzia powinna być włączona

Po uruchomieniu aplikacji należy przejść pod adres:
localhost:8080/swagger-ui.html (przy domyślnej konfiguracji spring boot).

swagger-example
Interfejs Swagger UI

UI pozwalana na wywołanie wszelkich metod REST – z parametrami, ciałem, nagłówkami!

Jeśli chcesz zobaczyć jak wygląda dokumentacja w postaci JSON’a to wystarczy przejść pod:
localhost:8080/v2/api-docs

Zawężenie udostępnianej dokumentacji

Często nie chcemy, aby wszystkie endpointy jakie posiadamy były dokumentowane. Wówczas rozwiązaniem jest zbudowanie konfiguracji w oparciu o obiekt Docket.

W tym celu powołaj beana Docket i wskaż konkretne pakiety lub endpointy usług które chcesz, by znalazły się w dokumentacji. Natomiast nieprzeskanowane usługi webowe nie będą częścią dokumentacji. Przykład implementacji może wyglądać następująco:

@Bean
public Docket get() {
    return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .paths(PathSelectors.ant("/api/**"))
            .apis(RequestHandlerSelectors.basePackage("pl.bykowski.springbootswaggerexample"))
            .build();
}

Co oznacza, że w dokumentacji zostaną uwzględnione tylko usługi spełniające dwa warunki:

  • endpoint jest wystawiony na /api/**
  • klasa kontrolera REST’owego znajduje się w ścieżce pl.bykowski.springbootswaggerexample

Swagger – krótki kurs wideo

Jeśli chcesz zobaczyć jakie dodatkowe możliwości niesie wykorzystanie tego narzędzia, oraz jak wdrożyć go w Spring Boot, jednocześnie rozszerzając domyślne możliwości generowania dokumentacji to odsyłam Cię do wideo:

Swagger - kurs wideo

Podsumowanie

Niestety wadą wykorzystania Swaggera jest mnogość adnotacji jaka pojawia się w naszym kodzie, przez co staje się on nieczytelny. Innymi słowy – Annotation Driven Design 😃 Natomiast to podejście prezentuje w przykładzie kodu z adnotacjami, które pozwalają uzupełnić generowaną dokumentacje kosztem czytelności. Możesz to sprawdzić analizując mój przykład swaggera na gicie.

Jakie są Twoje doświadczenia ze Swaggerem? A może znasz jakieś alternatywy dla niego lub inne przydatne narzędzia do budowania API, które warto znać?

Napisane przez Przemysław Bykowski

Aktywny programista i energiczny trener. Specjalizuje się w Spring Boot i uczę go w ramach AkademiaSpring.pl. Po godzinach udzielam się na YouTubach. Więcej o mnie.

Dodaj komentarz

Twój adres email nie zostanie opublikowany. Pola, których wypełnienie jest wymagane, są oznaczone symbolem *

Ładowanie…

Majowy festiwal szkoleń

Majowy festiwal szkoleń – lista otwartych szkoleń

Spring WebFlux

Spring WebFlux – programowanie reaktywne w Spring