JavaTrip and tricksWeb application

Swagger UI – przejrzysta wizualizacja zasobów API

Swagger UI

Czym jest Swagger?

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

Swagger sprawia, że projektowanie interfejsu API jest proste. Dużo osób utożsamia Swaggera z konkretnym produktem jaki jest Swagger UI. Nie bez przyczyny, gdyż Swagger UI jest genialny w swoich możliwościach i łatwy w zastosowaniu.

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. Jest on generowany automatycznie na podstawie specyfikacji OpenAPI.

Swagger UI i Spring Boot

Przykład zintegrowania aplikacji napisanej z wykorzystaniem Spring Boot i Swagger UI.

Dodanie zależności

Aby stworzyć projekt należy dodać dwie zależności. Pierwsza z nich dostarcza możliwości wykorzystania Swagger, 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>
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 Swagger powinna być włączona.

W tej klasie należy zdefiniować nowy obiekt zarządzany jakim jest Docket.
Docket zapewnia metody konfiguracji dla Swagger UI. W tej klasie definiowane są endpointy, które mają zostać uwzględnione i dostępne w ramach Swagger UI. Przykładowa implementacja umożlwiająca na zarządzanie wszystkimi endpointami wygląda następująco:

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
}

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

swagger-example
Swagger UI w użytkowaniu

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

Tags:
Show Buttons
Hide Buttons