Spring Boot – API Documentation using springdoc-openapi

Last Updated : 04 Jul, 2025

For any web application, having clear API documentation is important. It helps both developers and users understand how to use the API. Like what data to send, what kind of response to expect. That’s where springdoc-openapi comes in. It is a Java library that automatically creates API documentation for Spring Boot apps. The best part? It gives you the docs in formats like JSON, YAML, and also as a nice-looking web page (HTML). In this article, we’ll build a Spring Boot project and show how to use springdoc-openapi to generate API docs quickly and easily.

Prerequisites

Before starting the project, you must have a Spring Boot project

Create a Spring Boot project.

Setting up the Project

In this article, we will be working with OpenAPI 2.0.4 and Spring Boot 3.0.6. Enable automatic API documentation with springdoc-openapi.

Step 1: Add dependencies

Add the necessary dependency to your pom.xml file.

Java

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

If you don't have the validation dependency, you may face some errors; therefore, to avoid errors, include the below dependency if you don't have it

Java

<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-validation</artifactId>
 </dependency>

pom.xml:

Java

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>3.5.3</version>
		<relativePath/> <!-- lookup parent from repository -->
	</parent>
	<groupId>com.example</groupId>
	<artifactId>swager</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<name>swager</name>
	<description>Demo project for Spring Boot</description>
	<url/>
	<licenses>
		<license/>
	</licenses>
	<developers>
		<developer/>
	</developers>
	<scm>
		<connection/>
		<developerConnection/>
		<tag/>
		<url/>
	</scm>
	<properties>
		<java.version>17</java.version>
	</properties>
	<dependencies>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>
		<!-- https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-ui -->
		<dependency>
			<groupId>org.springdoc</groupId>
			<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
			<version>2.2.0</version>
		</dependency>


		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
		</dependency>
	</dependencies>

	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
			</plugin>
		</plugins>
	</build>

</project>

Step 2: Create Employee Class:

The Employee class is a simple Java model (POJO) that represents employee data with fields like id, name, and department.
It is used to define the structure of request and response bodies in API operations involving employee information.

Java

package com.example.swager;
public class Employee {
    private int id;
    private String name;
    private String department;

    // Constructors
    public Employee() {}
    public Employee(int id, String name, String department)
    {
        this.id = id;
        this.name = name;
        this.department = department;
    }

    // Getters and setters
    public int getId() { return id; }
    public void setId(int id) { this.id = id; }

    public String getName() { return name; }
    public void setName(String name) { this.name = name; }

    public String getDepartment() { return department; }
    public void setDepartment(String department)
    {
        this.department = department;
    }
}

Step 3: Create Service Class:

The EmployeeService class contains the business logic for handling employee operations like adding, updating, deleting, and fetching employees.
It acts as a middle layer between the controller and the data (in this case, an in-memory list).

EmployeeService.java:

Java

package com.example.swager;
import java.util.ArrayList;
import java.util.List;
import org.springframework.stereotype.Service;

@Service
public class EmployeeService {

    private List<Employee> employeeList = new ArrayList<>();

    public Employee saveEmployee(Employee employee)
    {
        employeeList.add(employee);
        return employee;
    }

    public Employee updateEmployee(Employee employee)
    {
        for (int i = 0; i < employeeList.size(); i++) {
            if (employeeList.get(i).getId()
                == employee.getId()) {
                employeeList.set(i, employee);
                return employee;
            }
        }
        return null;
    }

    public Employee deleteEmployee(int id)
    {
        for (Employee e : employeeList) {
            if (e.getId() == id) {
                employeeList.remove(e);
                return e;
            }
        }
        return null;
    }

    public List<Employee> getEmployees()
    {
        return employeeList;
    }
}

Step 4: Create Controller Class:

The EmployeeController class is a REST controller that handles incoming HTTP requests related to employee operations.
It maps endpoints like add, update, delete, and fetch to the corresponding methods in the EmployeeService class.

EmployeeController.java:

Java

package com.example.swager;
import java.util.List;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/employee")
public class EmployeeController {

    @Autowired private EmployeeService employeeService;

    @PostMapping("/addEmployee")
    public ResponseEntity<Employee>
    addEmployee(@RequestBody Employee employee)
    {
        return ResponseEntity.ok(
            employeeService.saveEmployee(employee));
    }

    @PutMapping("/updateEmployee")
    public ResponseEntity<Employee>
    updateEmployee(@RequestBody Employee employee)
    {
        return ResponseEntity.ok(
            employeeService.updateEmployee(employee));
    }

    @DeleteMapping("/deleteEmployee/{id}")
    public ResponseEntity<Employee>
    deleteEmployee(@PathVariable int id)
    {
        return ResponseEntity.ok(
            employeeService.deleteEmployee(id));
    }

    @GetMapping("/getEmployees")
    public ResponseEntity<List<Employee> > getEmployees()
    {
        return ResponseEntity.ok(
            employeeService.getEmployees());
    }
}

Step 5: Run Application:

Open the main class and run your application, then visit the following URL on your browser.

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

After running the application, navigate to http://localhost:8080/swagger-ui.html to view the swagger documentation.

Once your Spring Boot application is up and running with springdoc-openapi, Swagger UI automatically generates a clean, interactive interface for your REST APIs. This interface allows you to understand, visualize, and test endpoints without using external tools like Postman.

Let’s take a look at how it works using the following API as an example:

@PostMapping("/addEmployee")
public ResponseEntity<Employee> addEmployee(@RequestBody Employee employee) {
return ResponseEntity.ok(employeeService.saveEmployee(employee));
}

Here’s how Swagger UI displays this API:

HTTP Method: POST

Endpoint URL: /employee/addEmployee
Request Body: Accepts a JSON object representing an Employee, typically including fields like:
- id
- name
- department

The POST /employee/addEmployee endpoint allows users to send an Employee object in JSON format to be added to the system.

Swagger UI provides a form to input the employee details and test the API using the "Try it out" feature. According to the image below.

HTTP Method: GET

The GET /employee/getEmployees endpoint retrieves a list of all employees stored in the system.
In Swagger UI, you can simply click "Try it out" and "Execute" to view the complete employee list in JSON format. According images below: