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

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

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

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

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

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

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

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

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

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

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

BookController.java


              1234
            
@Tag(name = "Books", description = "API for managing books")
public class BookController {
    // struct
}

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

BookController.java


              1234
            
@Operation(summary = "Get a list of all books", description = "Returns a list of all available books")
public List<BookResponseDTO> getAllBooks() {
    return bookService.findAllBooks();
}

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

BookController.java


              12345
            
public BookResponseDTO getBookById(
        @Parameter(description = "ID of the book to retrieve", required = true)
        @PathVariable String id) {
    return bookService.getBookById(id);
}

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

BookController.java


              12345678
            
@ApiResponse(responseCode = "204", description = "Book successfully deleted")
@DeleteMapping("/{id}")
public void deleteBook(
    @Parameter(description = "ID of the book to delete", required = true)
  	@PathVariable String id
) {
    	bookService.deleteBook(id);
}

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

BookController.java


              12345678910111213
            
@ApiResponses({
        @ApiResponse(responseCode = "200", description = "Book successfully updated"),
        @ApiResponse(responseCode = "404", description = "Book not found")
})
@PutMapping("/{id}")
public BookResponseDTO updateBook(
  		@Parameter(description = "ID of the book to update", required = true) 
		@PathVariable String id,
  @RequestBody(description = "Updated book details", required = true) BookRequestDTO book
) {
    return bookService.updateBook(id, book);
}

Проєкт

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

Підсумок

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

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

Все було зрозуміло?

Дякуємо за ваш відгук!

Секція 3. Розділ 7

Запитати АІ

Запитайте про що завгодно або спробуйте одне із запропонованих запитань, щоб почати наш чат

Suggested prompts:

Can you explain more about how to use Swagger annotations in my own project?

What are some best practices for writing clear API documentation with Swagger?

How do I handle custom error responses in Swagger documentation?

Awesome!

Completion rate improved to 3.45

Свайпніть щоб показати меню

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

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

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

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

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

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

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

BookController.java


              1234
            
@Tag(name = "Books", description = "API for managing books")
public class BookController {
    // struct
}

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

BookController.java


              1234
            
@Operation(summary = "Get a list of all books", description = "Returns a list of all available books")
public List<BookResponseDTO> getAllBooks() {
    return bookService.findAllBooks();
}

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

BookController.java


              12345
            
public BookResponseDTO getBookById(
        @Parameter(description = "ID of the book to retrieve", required = true)
        @PathVariable String id) {
    return bookService.getBookById(id);
}

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

BookController.java


              12345678
            
@ApiResponse(responseCode = "204", description = "Book successfully deleted")
@DeleteMapping("/{id}")
public void deleteBook(
    @Parameter(description = "ID of the book to delete", required = true)
  	@PathVariable String id
) {
    	bookService.deleteBook(id);
}

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

BookController.java


              12345678910111213
            
@ApiResponses({
        @ApiResponse(responseCode = "200", description = "Book successfully updated"),
        @ApiResponse(responseCode = "404", description = "Book not found")
})
@PutMapping("/{id}")
public BookResponseDTO updateBook(
  		@Parameter(description = "ID of the book to update", required = true) 
		@PathVariable String id,
  @RequestBody(description = "Updated book details", required = true) BookRequestDTO book
) {
    return bookService.updateBook(id, book);
}

Проєкт

Підсумок

Все було зрозуміло?

Дякуємо за ваш відгук!

Секція 3. Розділ 7

Тестування RESTful API

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

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

Проєкт

Підсумок

Awesome!

Тестування RESTful API

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

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

Проєкт

Підсумок