DEV Community

Francisco Pereira
Francisco Pereira

Posted on

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:

Part Content
Part 01 Application Startup
Part 02 Settings and Database
Part 03 API Implementation
Part 04 Tests + Coverage
Part 05 Swagger Documentation

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:

Spring Initilizr Tags

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:

Image description

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>

Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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);
  }

}

Enter fullscreen mode Exit fullscreen mode

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:

Spring Boot logo

Server startup

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": "/"
}

Enter fullscreen mode Exit fullscreen mode

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.

Top comments (0)