Spring Boot Swagger Open API 3 with Example

Hey guys in this post, we will discuss documenting the Spring Boot REST APIs using Swagger Open API 3 with Example


The OpenAPI Specification, originally known as the Swagger Specification, is a specification for machine-readable interface files for describing, producing, consuming, and visualizing RESTful web services.

Read about Documenting Spring Boot REST APIs using Swagger

Complete example

Let’s create a step-by-step spring boot project and add swagger to the project to document REST APIs.

Read More:

Create spring boot project

There are many different ways to create a spring boot application, you can follow the below articles to create one –

>> Create spring boot application using Spring initializer
>> Create spring boot application in Spring tool suite [STS]
>> Create spring boot application in IntelliJ IDEA

Add maven dependencies

Open pom.xml and add the following dependencies –

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
		<relativePath /> <!-- lookup parent from repository -->
	<description>Spring data jpa</description>





spring-boot-starter-web dependency for building web applications using Spring MVC. It uses the tomcat as the default embedded container.

spring-boot-devtools dependency for automatic reloads or live reload of applications. spring-boot-starter-data-jpa dependency is a starter for using Spring Data JPA with Hibernate. lombok dependency is a java library that will reduce the boilerplate code that we usually write inside every entity class like setters, getters, and toString(). springdoc-openapi-ui dependency is for swagger Open API 3.

Configure the datasource

Open application.properties and add the following contents



Create an entity class

Create Employee.java inside the in.bushansirgur.springboot.entity package and add the following content

package in.bushansirgur.springboot.entity;

import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;
import javax.persistence.Table;

import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;

@Table(name = "tbl_employee")
public class Employee {
	@GeneratedValue(strategy = GenerationType.IDENTITY)
	private Long id;
	private String name;
	private String location;
  • @Data annotation which is a Lombok annotation, that will automatically create setters, getters, toString(), and equals() for us.
  • @Entity is a mandatory annotation that indicates that this class is a JPA entity and is mapped with a database table.
  • @Table annotation is an optional annotation that contains the table info like table name.

  • @Id annotation is a mandatory annotation that marks a field as the primary key

Create a Repository

Create EmployeeRepository.java inside the in.bushansirgur.springboot.repository package and add the following content

package in.bushansirgur.springboot.repository;

import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.stereotype.Repository;

import in.bushansirgur.springboot.entity.Employee;

public interface EmployeeRepository extends JpaRepository<Employee, Long> {


Create a Rest controller

Create EmployeeController.java inside the in.bushansirgur.springboot.controller package and add the following content

package in.bushansirgur.springboot.controller;

import java.util.List;
import java.util.Optional;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

import in.bushansirgur.springboot.entity.Employee;
import in.bushansirgur.springboot.repository.EmployeeRepository;

public class EmployeeController {
	private EmployeeRepository eRepo;
	public Employee save (@RequestBody Employee employee) {
		return eRepo.save(employee);
	public List<Employee> get () {
		return eRepo.findAll();
	public Employee get (@PathVariable Long id) {
		Optional<Employee> employee = eRepo.findById(id);
		if (employee.isPresent()) {
			return employee.get();
		throw new RuntimeException("Not found for the id "+id);
	public Employee update (@PathVariable Long id, @RequestBody Employee employee) {
		return eRepo.save(employee);
	public ResponseEntity<HttpStatus> delete (@PathVariable Long id) {
		return new ResponseEntity<HttpStatus>(HttpStatus.NO_CONTENT);

That’s it. Now spring boot will take care of documenting the APIs using swagger Open API 3.

Run the app

Run the application using the below maven command –

mvn spring-boot:run

Open the browser and enter the following URL –

  • localhost:8080/swagger-ui.html


That’s it for this post. I hope you enjoyed this post, if you did then please share this with your friends and colleagues. Also, you can share this post with your social media profiles. Thank you I will see you in the next post.

Bushan Sirgur

Hey guys, I am Bushan Sirgur from Banglore, India. Currently, I am working as an Associate project in an IT company.

Leave a Reply