У попередньому розділі було розглянуто Swagger та основи роботи з ним. У цьому розділі розглянемо його застосування на практиці та повністю завершимо створення нашого першого REST API!

Початок роботи зі Swagger

У відео було представлено основний інтерфейс Swagger та способи взаємодії з ним.

Для методів, які приймають тіло запиту, Swagger автоматично генерує JSON на основі об'єкта, який приймає поточна кінцева точка.

Крім того, якщо у вас є параметри в URL, ви можете легко вказати їх у відповідних полях.

Swagger також відображає можливі статус-коди для endpoint і вказує тип повернення об'єкта (JSON/XML).

І найголовніше — вам не потрібно було писати жодного додаткового коду для генерації цієї документації!

Достатньо просто додати залежність і налаштувати її за потреби (хоча часто налаштування не потрібне), щоб автоматично отримати документацію для вашого REST API!

Робота з анотаціями

Коротко розглянемо анотації, які були розглянуті у цьому розділі:

@Tag – Групує пов’язані ендпоінти та додає до них опис.

@Operation – Описує конкретний метод API, включаючи його призначення та короткий опис.

@Parameter – Описує параметри методу, такі як змінні шляху, параметри запиту тощо.

@ApiResponse – Описує одну конкретну можливу відповідь, включаючи код відповіді та його опис.

@ApiResponses – Визначає набір можливих відповідей для методу, включаючи коди стану та описи.

Проєкт

Також надаю посилання на проєкт на випадок, якщо щось не працює або якщо ви бажаєте ознайомитися з ним детальніше:

Підсумок

Swagger забезпечує автоматичне створення детальної документації для вашого API, що робить його зручнішим у використанні та тестуванні.

За допомогою анотацій таких як @Operation, @ApiResponse та @Parameter можна описати поведінку методів, параметрів і можливих відповідей без додавання зайвого коду. Це робить ваш REST API зрозумілішим і більш доступним для розробників.