Spring Boot Swagger 3 Example (2024)

To automate the documentation of our APIs, we used the SpringFox library for Swagger 2 in Spring Boot + Swagger 2 Example. However, even the most recent version (SpringFox 2.9.2) still uses version 2 of the OpenAPI Specification, and SpringFox does not yet support version 3. In this tutorial, we will utilise springdoc-openapi as a dependency for describing REST APIs in OpenAPI version 3 format.

In this tutorial, we'll show you how to use Swagger 3 with Spring Boot application.

What is Swagger?

Swagger is a JSON-based interface description language for specifying RESTful APIs for microservices/spring boot applications. To design, construct, describe, and consume RESTful web services, Swagger is used in conjunction with a set of open-source software tools. Automated documentation, code generation, and test-case generation are all included in Swagger.

What is OpenAPI?

The OpenAPI Specification (previously known as the Swagger Specification) is a machine-readable interface file specification for describing, generating, consuming, and visualising RESTful web services.

OpenAPI 3.0 is the latest version of the OpenAPI Specification, an open-source format for describing and documenting APIs.

Swagger vs OpenAPI

In short:

• OpenAPI = Specification
• Swagger = Tools for implementing the specification

Let's create Spring Boot Project from Spring Initializer site https://start.spring.io/

Project Structure

Maven Dependency

We simply add the springdoc-openapi-ui dependency to our pom.xml to have springdoc-openapi automatically build the OpenAPI 3 specification documents for our API:

<?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 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>

	<groupId>com.techgeeknext</groupId>
	<artifactId>spring-boot-swagger3-example</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<packaging>jar</packaging>

	<name>spring-boot-swagger3-example</name>
	<description>Demo project for Spring Boot Swagger3</description>

	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>2.2.4.RELEASE</version>
		<relativePath /> <!-- lookup parent from repository -->
	</parent>

	<properties>
		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
		<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
		<java.version>1.8</java.version>
	</properties>

	<dependencies>

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

		<dependency>
			<groupId>org.springdoc</groupId>
			<artifactId>springdoc-openapi-ui</artifactId>
			<version>1.5.9</version>
		</dependency>

	</dependencies>

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



</project>

Spring Boot Version 3 Swagger

Note: For Spring Boot Version 3 use below Swagger dependency in place of springdoc-openapi-ui.

<parent>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-parent</artifactId>
   <version>3.0.0</version>
   <relativePath/> <!-- lookup parent from repository -->
</parent>
.......
.......

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

Rest Controller

Create controller class to test swagger documentation using rest endpoint.

package com.techgeeknext.controller;

import com.techgeeknext.model.User;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import java.util.ArrayList;
import java.util.List;
import java.util.stream.Collectors;

@RequestMapping("/api")
@RestController
public class Swagger3RestController {

	List<User> users = new ArrayList<User>();
	{
		users.add(new User(1,"TechGeekNext-User1", "ADMIN", "user1@test.com"));
		users.add(new User(2,"TechGeekNext-User2", "SUPERVISOR", "user2@test.com"));
		users.add(new User(3,"TechGeekNext-User3", "USER", "user3@test.com"));
		users.add(new User(4,"TechGeekNext-User4", "USER", "user4@test.com"));
	}


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

	@RequestMapping(value = "/getUser/{id}", method = RequestMethod.GET, produces = "application/json")
	public User getUserById(@PathVariable(value = "id") int id) {
		return users.stream().filter(x -> x.getId()==(id)).collect(Collectors.toList()).get(0);
	}

	@RequestMapping(value = "/getUser/role/{role}", method = RequestMethod.GET, produces = "application/json")
	public List<User> getUserByRole(@PathVariable(value = "role") String role) {
		return users.stream().filter(x -> x.getRole().equalsIgnoreCase(role))
				.collect(Collectors.toList());
	}

}

Model Object

Create a User class.

package com.techgeeknext.model;


public class User {

	private int id;

	private String name;

	private String role;

	private String email;

	public User(int id, String name, String role, String email) {
		this.id = id;
		this.name = name;
		this.role = role;
		this.email = email;
	}

	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 getRole() {
		return role;
	}

	public void setRole(String role) {
		this.role = role;
	}

	public String getEmail() {
		return email;
	}

	public void setEmail(String email) {
		this.email = email;
	}

	@Override
	public String toString() {
		return "User{" +
				"id=" + id +
				", name='" + name + '\'' +
				", role='" + role + '\'' +
				", email='" + email + '\'' +
				'}';
	}
}

Swagger3 JSON Api Docs

Start the server by running maven build. The whole documentation should be available in JSON format if you open the link http://localhost:8080/v3/api-docs/.

Swagger3 UI Docs

Open http://localhost:8080/swagger-ui.html in browser to view the Swagger UI documentation.

You can expand any operation or rest end point and test as given below:

Download Source Code

The full source code for this article can be found on below.
Download it here - Spring Boot Swagger 3 Example