Integration of Swagger into a Spring Boot project: Document your APIs clearly and professionally

API documentation is just as essential as its development. It ensures that your endpoints are well understood, facilitates collaboration between teams, and improves the maintainability of your application.

In this article, we’ll explore how to integrate Swagger (via Springdoc OpenAPI) into a Spring Boot project to generate dynamic, interactive, and easy-to-maintain documentation.

Purpose of the Article

By the end of this article, you will be able to:

• Easily integrate Swagger (Springdoc OpenAPI) into a Spring Boot project
• Automatically generate complete and interactive API documentation
• Customize the documentation with precise titles, descriptions, and examples
• Document each endpoint with the appropriate annotations
• Test and explore your APIs directly from Swagger UI
• Export the documentation in JSON or YML format

Tools for the Project

Before getting started, here’s what you need:

✅ Java installed (version 17 recommended) ✅ Maven installed and configured ✅ An IDE such as IntelliJ IDEA, Eclipse, or VS Code ✅ A simple REST API with at least one controller

What is Swagger (Springdoc OpenAPI)?

Swagger (now standardized under the name OpenAPI) is a set of open-source tools that allow you to describe, consume, test, and document a REST API in an interactive and standardized way.

In the context of Spring Boot, the most popular tool for integrating Swagger is Springdoc OpenAPI, which automates the generation of documentation from source code and annotations.

Why use Swagger in a Spring Boot project?

Here are the main advantages of using Swagger:

• Automatic documentation: Endpoints are documented directly from the source code.
• Interactive interface (Swagger UI): Allows you to test endpoints directly from a browser without using Postman.
• Readability: The API structure is clear and easy to understand for developers, testers, and clients.
• Improves coordination between front-end and back-end by providing reliable, real-time documentation.
• Error handling, parameters, data schemas, response types: Everything is covered in the documentation.

Step 1: Add Swagger to Your Spring Boot Project

Add the following dependency to your pom.xml file:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.3.0</version>
</dependency>

Then synchronize your project (Maven > Reload Project).

Step 2: Access Swagger UI

Start your application, then open the following URL in your browser:

http://localhost:8081/swagger-ui/index.html

In my case, I’m using port 8081, so make sure to adjust the port accordingly.

Step 3: Customize Swagger

Add the following to your application.properties file:

# Defines the URL to access the OpenAPI JSON documentation
springdoc.api-docs.path=/api-docs
# Defines the URL to access the Swagger UI interface (web interface to test the documentation)
springdoc.swagger-ui.path=/swagger-ui/v1/employeeManagementSystem
# Sorts route groups (tags) alphabetically in Swagger UI
springdoc.swagger-ui.tagsSorter=alpha
# Sorts operations (endpoints) by HTTP method (GET, POST, PUT, DELETE)
springdoc.swagger-ui.operationsSorter=method

Here is a screenshot of my application.properties file

Then create a configuration class to enrich your documentation:

package com.sid.employeeManagementSystemBackend.config;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Employee Management API")
                        .version("1.0.0")
                        .description("Employee Management API Documentation")
                        .contact(new Contact()
                                .name("Sidaoui Mohamed Amine")
                                .email("mssidaoui@gmail.com")
                                .url("https://www.linkedin.com/in/sidaouimohamedamine/"))
                        .license(new License()
                                .name("Apache 2.0")
                                .url("http://springdoc.org")));
    }
}

Step 4: Document the Endpoints

Add Swagger annotations to the controller:

package com.sid.employeeManagementSystemBackend.controller;

import com.sid.employeeManagementSystemBackend.entity.Employee;
import com.sid.employeeManagementSystemBackend.service.EmployeeServiceImpl;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.ExampleObject;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@CrossOrigin("*")
@RestController
@RequestMapping("api/employee/")
@Tag(name = "Employee", description = "Employee Operations")
public class EmployeeRestController {

        @Autowired
        private EmployeeServiceImpl employeeService;

        @Operation(
                summary = "Create new employee",
                description = "Create a new employee in the database",
                responses = {
                        @ApiResponse(responseCode = "200", description = "Employee created successfully"),
                        @ApiResponse(responseCode = "400", description = "Invalid Request")
                }
        )

        @PostMapping("addEmployee")
        public ResponseEntity<Employee> createEmployee(
                @io.swagger.v3.oas.annotations.parameters.RequestBody(
                        description = "Employee data",
                        required = true,
                        content = @Content(
                                schema = @Schema(implementation = Employee.class),
                                examples = @ExampleObject(
                                        value = """
                    {
                      "firstName": "sidaoui",
                      "lastName": "Mohamed Amine",
                      "email": "mssidaoui@gmail.com"
                    }
                    """
                                )
                        )
                )
                @RequestBody Employee employee
        ) {
                return ResponseEntity.ok(employeeService.addEmployee(employee));
        }

        @Operation(summary = "Retreive all employee")
        @GetMapping("getAllEmployee")
        public List<Employee> getAllEmployee(){
            return employeeService.getAllEmployee();
        }

        @Operation(summary = "Retreive an employee by Id")
        @GetMapping("getEmployeeById/{id}")
        public Employee getEmployeeById(@PathVariable("id") Long id){
                return employeeService.getEmployeeById(id);
        }

        @Operation(summary = "Update an employee")
        @PutMapping("updateEmployee/{id}")
        public Employee updateEmployee(@PathVariable("id") Long id,@RequestBody Employee employee){
                return  employeeService.updateEmployee(id,employee);
        }
        @Operation(summary = "Delete an employee")

        @DeleteMapping("deleteEmployee/{id}")
        public ResponseEntity<Void> deleteEmployee(@PathVariable Long id){
                return employeeService.deleteEmployee(id);
        }

        @Operation(summary = "Get Employee Number")
        @GetMapping("getEmployeeNumber")
        public Integer getEmployeeNumber(){
                return employeeService.getEmployeeNumber();
        }

}

@Tag — Used by Swagger to categorize endpoints @Operation — Documents a REST method in Swagger @ApiResponse — Defines the expected response codes

Now, you can finish the other controllers in the same way

Step 5: Test Endpoints in Swagger UI

Swagger offers you:

• A detailed description of each endpoint
• Input and output parameters
• A “Try it out” button to execute API calls directly
• Expected HTTP response codes

Step 6: Export Your Documentation

Swagger exposes your API in the following formats:

• 📄 JSON: http://localhost:8081/api-docs
• 📄 YAML: http://localhost:8081/api-docs.yaml

These formats can be used with:

• Swagger Codegen (to generate API clients)
• Postman (for automatic import)
• Redoc (as an alternative way to display the documentation)

Conclusion

Integrating Swagger into your Spring Boot project means:

• Gaining clarity and professionalism
• Facilitating collaboration between teams
• Speeding up front-end testing and integration

We successfully integrated Swagger into a Spring Boot project to automatically document our REST APIs. Throughout this article, we covered the key steps: adding dependencies, customizing the Swagger UI interface, documenting endpoints, and exporting files.

You can access and clone the complete project using this link(**https://github.com/sidaouiMohamedamine/employee-management-backend**).

If you have any questions, feel free to contact me through my LinkedIn profile.**https://www.linkedin.com/in/sidaouimohamedamine/**

**http://www.sidaouimohamedamine.com/**