wtorek, 16 września 2014

REST API part 2

Inspiracją do napisania tego posta był projekt mojego kolegi z pracy, który użył swaggera do projektu Play'a jako obsługa REST API (konsumowanie i produkowanie).
Mi wydawało się, że korzystając kiedyś z Typesafe Activator już wcześniej widziałem w którejś aplikacji typu demo takie połączenie.
Ok. Wyzwanie na dziś : Integracja Swagger + Spring Boot. 
W poprzednim poście pokazałem jak projektować i czym się kierować podczas tworzenia serwisów REST'owych. (czyli dobre praktyki)
Swagger jest to framework, którego zadaniem jest wizualizacja, konsumowanie i produkowanie wiadomości w formacie JSON jak i XML.
Dzięki niemu nie musimy zaglądać do dokumentacji czy kodu źródłowego, wszystko mamy podane jak na talerzu w możliwie wygodniej i czytelnej dla użytkownika postaci.
Swagger Spring MVC używa @Annotation do budowy dokumentacji serwisów.

Krok 1:Konfiguracja gradle:
Krok 2:
Konfiguracja springa:

Pamiętaj o stworzeniu profilu : tak naprawdę swagger sprawdzi się fazie developmentu. (@Profile("dev"))

Krok 3: Opisujemy usługę :  przykładowa konfiguracja w kontrolerach
Opcjonalnie możemy opisać klasy domenowe lub zwykłe DTO:
Na konsoli widzę coś takiego : -> czyli sukces :)
Wygenerowane info -> czyli opis usług wystawionych przez aplikację (info definiujemy w SwaggerConfig.java - patrz wyżej):
Przy uderzenia na główny URL z przeglądarki odpala się index.html. Plik ten pochodzi z webjara  org.ajar:swagger-spring-mvc-ui:0.2, którego definiowaliśmy w gradle.

TIP : używaj zawsze webjar'ów są kompaktowe i projekt de facto będzie zawierał mniej plików. Webjary podpinasz za pomocą static-resource ze Springa.
W przypadku javaConfig - korzystając z obiektu ResourceHandlerRegistry registry



lub za pomocą xml :

Krok 4: Odpalamy i wklejamy link api-docs do swagger (można zedytować index.html i wstawić tam odpowiedniego dla nas linka zamiast cały czas wklejać odpowiedni..)























Ukazuje nam się nasze API: )

Listujemy , lub pobieramy


























Mniej więcej tak to wygląda....
Dokładny opis integracji znajdziecie u źródła czyli tutaj.
Integracja i customize'zacja dla swagger UI opisana jest tutaj.

W następnych postach pokaże inne narzędzia i sposoby do szybkiego korzystania z REST API w naszych aplikacjach. Swagger nie jest jedynym narzędziem do tego aby sprawnie używać serwisy restowe. Ale o tym potem...


Brak komentarzy:

Prześlij komentarz