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).
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:
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ć?
