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.

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.

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

@Parameter – Describes the method parameters, such as path variables, query parameters, and so on.

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

@ApiResponses – Defines a set of possible responses for the method, including status codes and descriptions.

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.