Swagger — це набір інструментів для проектування, створення, документування та використання RESTful веб-сервісів. Цей інструментарій дозволяє розробникам та архітекторам програмного забезпечення легко керувати всім життєвим циклом API, включаючи його дизайн, тестування, документування та забезпечення сумісності.

Переваги використання Swagger:

1. Документація API “як код”: Swagger дозволяє документувати API у форматі, який може бути як читабельним людиною, так і машиною. Це означає, що документація може бути автоматично генерована та оновлюватися разом з API.
2. Інтерактивна документація: Swagger забезпечує користувачам можливість взаємодіяти з API прямо через документацію за допомогою Swagger UI. Це дозволяє користувачам розуміти можливості API швидше та легше інтегрувати з ним.
3. Спільна робота та генерування клієнтського коду: Swagger спрощує співпрацю між розробниками у команді та може автоматично генерувати клієнтський код для різних мов програмування.

Як працює Swagger?

Swagger використовує гнучку схему даних у форматі, відомому як OpenAPI Specification (OAS). Ця схема описує API у форматі JSON або YAML, дозволяючи програмам розуміти та взаємодіяти з API без необхідності доступу до коду сервера. Специфікація OpenAPI містить всю необхідну інформацію про API, включаючи доступні операції, параметри вхідних даних, формати вихідних даних, можливі помилки тощо.

Swagger UI

Swagger UI — це динамічно генерований веб-інтерфейс для документації API. Цей інтерфейс дозволяє користувачам переглядати документацію та взаємодіяти з API без початкового коду. Swagger UI може бути легко інтегрованим у будь-яку веб-службу.

Ось як ви можете підключити Swagger до Spring Boot та налаштувати сторінку Swagger UI.

Крок 1: Додавання залежностей

Для початку додайте необхідні залежності до вашого pom.xml файлу. Якщо ви використовуєте Maven, то ваш файл pom.xml має виглядати приблизно так:

<dependencies>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-boot-starter</artifactId>
        <version>3.0.0</version>
    </dependency>
</dependencies>

Якщо ви використовуєте Gradle, додайте таку залежність у файл build.gradle:

gradleimplementation 'io.springfox:springfox-boot-starter:3.0.0'

Крок 2: Конфігурація Java для Swagger

Створіть Java конфігураційний клас, який налаштує Swagger 2 для вашого Spring Boot проекту. Ви можете створити клас конфігурації у своєму пакеті, як показано нижче:

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {                                    
    @Bean
    public Docket api() { 
        return new Docket(DocumentationType.SWAGGER_2)  
          .select()                                  
          .apis(RequestHandlerSelectors.basePackage("com.example.yourapp"))              
          .paths(PathSelectors.any())                          
          .build();                                           
    }
}

Вище, RequestHandlerSelectors.basePackage("com.example.yourapp") вказує пакет, де знаходяться ваші контролери, і потрібно замінити “com.example.yourapp” на відповідний пакет вашого проекту.

Крок 3: Доступ до Swagger UI

Після інтеграції і налаштування Swagger, ви можете доступити Swagger UI за адресою:

http://localhost:8080/swagger-ui/

Замініть localhost:8080 на URL вашого сервера та порт. Swagger UI автоматично завантажить вашу документацію API та надасть інтерактивний інтерфейс для тестування API.

Крок 4: Налаштування Swagger UI

Ви можете налаштувати інформацію, яка відображається у Swagger UI, додавши більше параметрів у метод Docket api(). Наприклад, ви можете вказати інформацію про API, таку як назва, опис, версія, терміни використання, контактну інформацію тощо.

import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;

// В середині методу Docket api()
.apiInfo(new ApiInfo(
    "Назва API", 
    "Опис API", 
    "Версія API", 
    "Терміни використання", 
    new Contact("Ім'я", "URL", "email"), 
    "Ліцензія", "URL Ліцензії", Collections.emptyList()
))

Ці кроки допоможуть вам інтегрувати та налаштувати Swagger для Spring Boot, щоб ви могли легко та ефективно управляти своїм API.