Spring Boot 3 + Swagger (OpenAPI) Hello World Example

In this tutorial we will be implementing OpenAPI specification using Spring Boot 3. We will be looking at what are is the OpenAPI Specification and how it relates to swagger. In the next tutorial we will be implementing swagger configuration for Spring Boot 3 + Basic Authentication. Also later we will be implementing swagger configuration for Spring Boot 3 + JWT Authentication. In this tutorial we will be looking at what is Swagger and Open API Specification. What is the need for them and also understand the difference between them. We will be implementing swagger configuration for Spring Boot 3 + MySQL + CRUD example we implemented before.

What is OpenAPI Specification and the need for it

Modern applications are developed as microservices. APIs in microservices refer to the Application Programming Interfaces that allow different microservices to communicate with each other. APIs act as the interface between these microservices, enabling them to interact and share data or functionality. These API's using which microservices communicate with each other can be of any type RESTful API, GraphQL API, gRPC API. For example for Spring Boot 3 + MySQL + CRUD example we have exposed REST API's to perform CRUD operations.

In microservices architecture we have may have hundreds/thousands of applications that interact with each other using API's.


Now consider the scenario where we are developing an some APIs for a microservice. We need to share these details with the client developer team and the QA team who will be consuming this API's. So that these teams can also begin their work simultaneously. So we need to share the API documentation with the client developer and QA team. If the API developers do this documentation manually they may miss some details which may cause issues. This is where OpenAPI specification comes into picture.
So OpenAPI specification is needed for

• Proper API Documentation - Missing details in API documentation might lead to developers spending more time to understand code, perform more analysis and tests. This leads to more time consumed.
• Team Collaboration -API developement may need collaboration between various stakeholders like developers, clients, QA team, business analysts. Define the request and response parameters.
• Standard Documentation - OpenAPI is a standard which is followed by all organizations. So each organization will not have the need to develop by each organization seperately.

Difference between OpenAPI and Swagger

Previously the specification which described the API was called Swagger Specification. After Swagger 2 this specification is renamed as Open API Specification(OAS). Swagger is now a collection of tools that use OpenAPI Specification for API development.

Implementation

In a previous tutorial we had implemented Spring Boot 3 + MySQL CRUD Example. We will be implementing swagger for this project.
Modify the pom.xml to add the openapi documentation

<?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.2.2</version>
		<relativePath /> <!-- lookup parent from repository -->
	</parent>
	<groupId>com.javainuse</groupId>
	<artifactId>boot-mysql-crud</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<name>boot-mysql-crud</name>
	<description>Demo project for Spring Boot</description>
	<properties>
		<java.version>17</java.version>
	</properties>
	<dependencies>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-data-jpa</artifactId>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>

		<dependency>
			<groupId>com.mysql</groupId>
			<artifactId>mysql-connector-j</artifactId>
			<scope>runtime</scope>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
		</dependency>
		<dependency>
			<groupId>org.springdoc</groupId>
			<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
			<version>2.0.2</version>
		</dependency>
	</dependencies>

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

</project>

Next modify the application.properties add the springdoc.api-docs.path. The springdoc.api-docs.path is a property in Spring Boot applications that allows you to customize the base path where the OpenAPI documentation is served.

spring.datasource.url= jdbc:mysql://localhost/javainusedb?createDatabaseIfNotExist=true&useSSL=false&allowPublicKeyRetrieval=true
spring.datasource.username= root
spring.datasource.password= root

spring.jpa.properties.hibernate.dialect= org.hibernate.dialect.MySQLDialect
spring.jpa.hibernate.ddl-auto= update

springdoc.api-docs.path = /javainuse-openapi

Start the spring boot application and go to http://localhost:8080/swagger-ui/index.html. We can see the swagger ui.

If we now go to http://localhost:8080/javainuse-openapi, we can see the OpenAPI specification.

If we go to the Swagger Editor and copy the openapi documentation we can see the swagger api's

If suppose we want to disable or not show the Try It Out button.
For this we will need to add the following properties in the configuration

springdoc.swagger-ui.try-it-out-enabled=false
springdoc.swagger-ui.supportedSubmitMethods=

If we now go to http://localhost:8080/swagger-ui/index.html, the try it out button is not shown.

Download Source Code

Download it - Spring Boot 3+ Swagger