Creating a REST API using Spring Boot + Tests + Documentation [part 01]
Tags: webdev, java, springboot
Published: 2023-02-01 18:16:23

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](https://dev.to/franciscotis/creating-a-rest-api-using-spring-boot-tests-documentation-part-02-1a4i)  |
|   Part 03   |    [API Implementation](https://dev.to/franciscotis/creating-a-rest-api-using-spring-boot-tests-documentation-part-03-1m5e)   |
|   Part 04   |     [Tests + Coverage](https://dev.to/franciscotis/creating-a-rest-api-using-spring-boot-tests-documentation-part-04-4190)    |
|   Part 05   |  [Swagger Documentation](https://dev.to/franciscotis/creating-a-rest-api-using-spring-boot-tests-documentation-part-05-1pd6)  |

---

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](https://start.spring.io) website

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

![Spring Initilizr Tags](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/hpid0utbkpwvmejfza8d.png)

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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/px7lwa85g7wub28q14bx.png)

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:


![Spring Boot logo](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/lp9p27lyqhklnirk8x5s.png)


![Server startup](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/gbfsr5lorew78zh13z1s.png)

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](https://dev.to/franciscotis/creating-a-rest-api-using-spring-boot-tests-documentation-part-02-1a4i) we will carry out the actual implementation of our API, performing the configuration with the database and coding the access routes.