Creating a REST API using Spring Boot + Tests + Documentation [part 01]

Hi!

In this 5 parts tutorial I will be teaching you how to develop a REST API using Spring Boot. In each part we will be focusing on a different functionality, this division is shown in the following table:

It is expected that from this first part you will learn the following:

• Initializing a new Spring Boot application using Spring Initializr
• Project structure

For this tutorial the following tools are used:

• JDK 17
• IntelliJ
• Maven
• Insomnia
• MySQL database

Step 01 - Initializing the project

Spring Boot has a very simple and intuitive initialization tool, with a few steps you can already generate a Spring application with some dependencies. You can do this by going to the Spring Initializr website

For this project, we can leave the following tags and dependencies:

In the left part of the screen, we can see some technical specifications of the project.
For project management, we use Maven along with Java. The Spring Boot version we are using is 3.0.2.

In the metadata part, we mainly inform the name of the project. For this tutorial we will be creating a simple library system where we will only be storing book information. Therefore, we can name the project Simple Library.

In this tutorial we will not be exporting our project and deploying it, so we can put Packaging with its default value (.jar). However, if you are going to export this project, you can select the best option for you.

Finally, we have that the version to be used of java is 17.

In the right part of the screen we can inform Initializr which dependencies we would like to have in our project:

• Spring Boot DevTools: we have access to some important developer tools, one of which is LiveReload which checks if a modification has been made to the project to restart the server automatically.

• Lombok: we can insert some annotations into our classes to replace the manual insertion of getters, setters and constructors. Thus increasing developer productivity and decreasing the amount of code to be written in the class.

• SpringWeb: it is one of the most important dependencies, from which we can create web services. With this dependency we can have access to the servlet-based implementation, RESTful services and many other features.

By clicking on the Explore button you will have access to the file that will be generated containing your application:

Your pom.xml file should look like this:

<?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.0.2</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.simplelibrary</groupId>
    <artifactId>simplelibraryAPI</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>simplelibraryAPI</name>
    <description>A simple library to practice</description>
    <properties>
        <java.version>17</java.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-devtools</artifactId>
            <scope>runtime</scope>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </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>
                <configuration>
                    <excludes>
                        <exclude>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
            </plugin>
        </plugins>
    </build>

</project>

By clicking on Generate all the files needed for the application will be compressed and downloaded to your machine. From now on you can open the folder in any IDE of your choice. In this tutorial I will be using IntelliJ

Step 02 - Checking the project structure

When opening the project we can see the following structure:

📦 simplelibraryAPI
├─ src
│  ├─ main
│  │  ├─ java
│  │  │  └─ com
│  │  │     └─ simplelibrary
│  │  │        └─ simplelibraryAPI
│  │  │           └─ SimplelibraryApiApplication.java
│  │  └─ resources
│  │     ├─ db
│  │     │  └─ migration
│  │     ├─ static
│  │     ├─ templates
│  │     └─ application.properties
│  └─ test
│     └─ java
│        └─ com
│           └─ simplelibrary
│              └─ simplelibraryAPIs
│                 └─ SimplelibraryApiApplicationTests.java
├─ .mvn
├─ .gitignore
├─ mvnw
├─ mvnw.cmd
└─ pom.xml

This is the basic structure of a Spring Boot project, throughout the parts of this tutorial we will be adding new folders to keep the project more organized.

From the SimplelibraryApiApplication.java file our application will be initialized, inside this class there is the main method that will call the run method of the SpringApplication class.

package com.simplelibrary.simplelibraryAPI;

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

@SpringBootApplication
public class SimplelibraryApiApplication {

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

}

Notice the @SpringBootApplication annotation. It is important to inform Spring that this is the main class of our application and that our server will be initialized from there.

The application.properties file will contain some important properties for our system. We will understand better about it later on, especially when we are going to configure the database.

Step 03 - Running the project

After executing the previous steps, your code is ready to run. Using the IDE of your choice, when starting the server you will have the following result in the terminal:

As you can see, the server is running at address: http://localhost:8080

However, when making a request to this URL, you will find the following response from the server:

{
    "timestamp": "2023-01-31T18:08:42.607+00:00",
    "status": 404,
    "error": "Not Found",
    "message": "No message available",
    "path": "/"
}

It turns out that so far we have not mapped any route to the source url ("/"). Therefore, we need to perform the mapping, but we will see this in part 02 of our tutorial!

What we learned in this tutorial

So far, you've seen how to create the initial project in Spring Boot, using Spring Initializr. In addition to seeing a little about its structure. In part 02 we will carry out the actual implementation of our API, performing the configuration with the database and coding the access routes.