Testing RESTful API

In the previous chapter, we were introduced to Swagger and how to work with it. In this chapter, we will explore its usage through a practical example and fully complete our first REST API!

Getting Started with Swagger

In the video, you were introduced to the main interface of Swagger and how to interact with it.

For methods that accept a request body, Swagger automatically generates JSON based on the object that the current endpoint receives.

Additionally, if you have parameters in the URL, you can easily specify them in the corresponding fields.

Note
The number of fields to fill out will match the number of parameters in the request.

Swagger also shows the possible status codes for the endpoint and specifies the return type of the object (JSON/XML).

And most importantly—you didn’t have to write any additional code to generate this documentation!

Simply adding the dependency and configuring it if necessary (although often no configuration is required) is enough to automatically get documentation for your REST API!

Working with Annotations

Let's briefly review the annotations covered in this chapter:

@Tag – Groups related endpoints and adds a description to them.

BookController


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

@Operation – Describes a specific API method, including its purpose and a brief description.

BookController


              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 – Describes the method parameters, such as path variables, query parameters, and so on.

BookController


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

@ApiResponse – Describes a single specific possible response, including the response code and its description.

BookController


              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 – Defines a set of possible responses for the method, including status codes and descriptions.

BookController


              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);
}

Project

I am also providing a link to the project in case something isn’t working or if you want to explore it in more detail:

Summary

Swagger allows for the automatic generation of detailed documentation for your API, making it easier to use and test.

With annotations such as @Operation, @ApiResponse, and @Parameter, you can describe the behavior of methods, parameters, and possible responses without adding extra code. This makes your REST API clearer and more accessible to developers.

Tudo estava claro?

Seção 3. Capítulo 7