Search Tutorials


Spring Boot + Swagger 3 (OpenAPI 3) Hello World Example | JavaInUse

Spring Boot + Swagger 3 (OpenAPI 3) Hello World Example

Introduction

In previous tutorial we had implemented Spring Boot + Swagger Hello World Example. We saw what is swagger and why is it useful to implement. The example used an older version of Swagger.

What is Swagger and Open API Specification

OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs. An OpenAPI file allows you to describe your entire API.
Swagger is a set of open-source tools built around the OpenAPI Specification that can help you design, build, document and consume REST APIs.

Spring Boot Swagger Open-api3
Over the past few years, Swagger has become the standard for defining or documenting your API. Formerly known as the Swagger Specification, this format has been donated to the Open API Initiative (or OAI) which is a Linux Foundation Collaborative Project.
On July 2017, the OpenAPI Specification 3.0.0 was finally released by the Open API Initiative. This has improved the specifications over the previous ones.
The springdoc-openapi java library implements the OpenAPI Specification 3.0.0 and will be used here.

Spring Boot Swagger- Table of Contents

Spring Boot + Swagger Example Hello World Example Spring Boot + Swagger- Understanding the various Swagger Annotations Spring Boot + Swagger + Profile - Implementing Spring Boot Profile for a Swagger application Spring Boot + Swagger 3 (OpenAPI 3) Hello World Example Spring Boot + Swagger 3 (OpenAPI 3) + Security Example

Video

This tutorial is explained in the below Youtube Video.

Lets Begin

We will be creating a spring boot project and then implementing the OpenAPI 3 specification for documenting the REST API's. The maven project we will be developing is as follows -
Spring Boot Swagger Open-api3 maven
The pom.xml will have the springdoc-openapi dependency.
<?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>2.2.8.RELEASE</version>
		<relativePath /> <!-- lookup parent from repository -->
	</parent>
	<groupId>com.javainuse</groupId>
	<artifactId>boot-swagger-3</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<name>boot-swagger-3</name>

	<properties>
		<java.version>1.8</java.version>
	</properties>

	<dependencies>
		<!-- Swagger UI -->
		<dependency>
			<groupId>org.springdoc</groupId>
			<artifactId>springdoc-openapi-ui</artifactId>
			<version>1.2.32</version>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>
	</dependencies>

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

</project>
   




Create the domain class named Employee. Also later in the controller class we will be performing CRUD operations for the employee object. So we will also be overriding the equals and hashCode methods in the Employee class.
package com.javainuse.model;

public class Employee {
	private String empId;
	private String name;
	private String designation;
	private double salary;

	public Employee() {
	}

	public String getName() {
		return name;
	}

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

	public String getDesignation() {
		return designation;
	}

	public void setDesignation(String designation) {
		this.designation = designation;
	}

	public double getSalary() {
		return salary;
	}

	public void setSalary(double salary) {
		this.salary = salary;
	}

	public String getEmpId() {
		return empId;
	}

	public void setEmpId(String empId) {
		this.empId = empId;
	}

	@Override
	public int hashCode() {
		final int prime = 31;
		int result = 1;
		result = prime * result + ((designation == null) ? 0 : designation.hashCode());
		result = prime * result + ((empId == null) ? 0 : empId.hashCode());
		result = prime * result + ((name == null) ? 0 : name.hashCode());
		long temp;
		temp = Double.doubleToLongBits(salary);
		result = prime * result + (int) (temp ^ (temp >>> 32));
		return result;
	}

	@Override
	public boolean equals(Object obj) {
		if (this == obj)
			return true;
		if (obj == null)
			return false;
		if (getClass() != obj.getClass())
			return false;
		Employee other = (Employee) obj;
		if (designation == null) {
			if (other.designation != null)
				return false;
		} else if (!designation.equals(other.designation))
			return false;
		if (empId == null) {
			if (other.empId != null)
				return false;
		} else if (!empId.equals(other.empId))
			return false;
		if (name == null) {
			if (other.name != null)
				return false;
		} else if (!name.equals(other.name))
			return false;
		if (Double.doubleToLongBits(salary) != Double.doubleToLongBits(other.salary))
			return false;
		return true;
	}

}

In the controller class, we will be creating a list of employees. Then we will be exposing the REST GET, POST and DELETE endpoints. Create the controller class as follows-
package com.javainuse.controllers;

import java.util.ArrayList;
import java.util.List;

import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import com.javainuse.model.Employee;

@RestController
public class EmployeeController {

	private List<Employee> employees = createList();

	@RequestMapping(value = "/employees", method = RequestMethod.GET, produces = "application/json")
	public List<Employee> firstPage() {
		return employees;
	}

	@DeleteMapping(path = { "/{id}" })
	public Employee delete(@PathVariable("id") int id) {
		Employee deletedEmp = null;
		for (Employee emp : employees) {
			if (emp.getEmpId().equals(id)) {
				employees.remove(emp);
				deletedEmp = emp;
				break;
			}
		}
		return deletedEmp;
	}

	@PostMapping
	public Employee create(@RequestBody Employee user) {
		employees.add(user);
		System.out.println(employees);
		return user;
	}

	private static List<Employee> createList() {
		List<Employee> tempEmployees = new ArrayList<>();
		Employee emp1 = new Employee();
		emp1.setName("emp1");
		emp1.setDesignation("manager");
		emp1.setEmpId("1");
		emp1.setSalary(3000);

		Employee emp2 = new Employee();
		emp2.setName("emp2");
		emp2.setDesignation("developer");
		emp2.setEmpId("2");
		emp2.setSalary(3000);
		tempEmployees.add(emp1);
		tempEmployees.add(emp2);
		return tempEmployees;
	}
}
Finally create the Spring Boot bootstrap class as follows-
package com.javainuse;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class SwaggerSpringDemoApplication {

	public static void main(String[] args) {
		SpringApplication.run(SwaggerSpringDemoApplication.class, args);
	}

}
Start the project. If we now go to localhost:8080/swagger-ui.html we can see the swagger ui as follows-
Spring Boot Swagger UI
Also if we go to http://localhost:8080/v3/api-docs, the OpenAPI description will be available at the following url for json format -
Spring Boot Swagger docs
If suppose we want to change the title and other properties for swagger. We can do it using the as follows-
package com.javainuse;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Info;

@SpringBootApplication
@OpenAPIDefinition(info = @Info(title = "Employees API", version = "2.0", description = "Employees Information"))
public class SwaggerSpringDemoApplication {

	public static void main(String[] args) {
		SpringApplication.run(SwaggerSpringDemoApplication.class, args);
	}

}
If we now go to localhost:8080/swagger-ui.html we can see the swagger ui as follows-
Spring Boot Swagger3 UI
If suppose we want to define a custom path of our documentation. We define it in the application.properties of our Spring Boot project:
springdoc.api-docs.path = /javainuse-openapi
If we now go to http://localhost:8080/javainuse-openapi we can see the documentation
Spring Boot Swagger3 UI documentation

Download Source Code

Download it - Spring Boot + Swagger 3 (OpenAPI 3) Example