A Guide to Creating Spring Boot Projects With Spring Initializr

A while ago, I wanted to learn how to create REST APIs with Spring Boot, a popular Java framework used by companies such as Netflix, Walmart, PayPal, Udemy, and many others. I had some experience building REST APIs with libraries like Jersey, Jetty, and Jackson, but I wanted to try Spring Boot.

You can use a tool called Spring Initializr to generate the initial Spring Boot boilerplate code by accessing it through an online form. The form creates a zip file that contains the basic project structure and configuration.

To use Spring Initializr:

1. Go to start.spring.io, where you can find the Spring Initializr web tool.
2. Fill out the form, specifying your desired build tool, programming language, Spring Boot version, project metadata, and dependencies.
3. Click the GENERATE button at the bottom of the screen to download the autogenerated code as a zip file.
4. Extract the contents of this zip file.

The Spring Initializr Form Options

At first, the many options available on the Spring Initializr form can be overwhelming. The following sections offer explanations for each form option and suggestions on which choices to make for your project.

The Project Option

The project option allows you to choose a build tool for your project. The purpose of build tools is to automate and manage the process of building software projects, which includes tasks like handling external dependencies, compiling source code, running tests, and packaging everything into distributable formats, like JARs. There are three options:

1. Gradle – Groovy
2. Gradle – Kotlin
3. Maven

Gradle has two options because it can use a domain-specific language (DSL) based on Groovy or Kotlin. If you have used Gradle before but are still confused about the difference, you may have been using Groovy as the DSL without knowing it since it is Gradle’s original DSL.

If you do not know which option to pick, I would suggest Gradle because working with a DSL is more pleasant than XML, in my opinion. To better understand the differences between Gradle and Maven, consider reading this summary for more information.

The Language Option

The language option lets you choose a JVM-compatible programming language for your Spring Boot project. There are three options:

1. Kotlin
2. Groovy

If you are not familiar with Kotlin or Groovy, Java is what you want.

The Spring Boot Option

The Spring Boot option enables you to select the version of Spring Boot to use in your project. It’s important to note that Spring Boot 2.x.x and 3.x.x are distinct major versions. If you are starting a new Spring Boot project, I recommend choosing a stable 3.x.x version.

Also, note that some versions may be labeled M1, M2, RC1, or SNAPSHOT, indicating they are pre-release versions and not considered stable or production-ready. Be careful when using these versions, as they may contain bugs or incomplete features due to being in active development.

The Project Metadata Options

The project metadata options enable you to choose configuration details and settings for your project. There are seven metadata fields:

1. Group – The unique identifier of your organization or project, typically written in reversed domain name notation. It helps to ensure that your package names do not conflict with packages from other organizations or projects. If you are creating a personal project, feel free to leave it as com.example.
2. Artifact – The name of the archive generated by your build tool. The artifact usually has the same value as the name field below.
3. Name – The name used for the project’s root directory, as well as the default name of the main application class.
4. Description – A field that provides a short description of the project.
5. Package name – The name of the package generated Java classes will be placed in. The package name should be a combination of the group and name fields above (e.g., com.example.myproject).
6. Packaging – Packaging refers to the type of archive your build tool will generate. Two common packaging types are JAR (Java Archive) and WAR (Web Archive). JAR files are usually used for standalone applications, libraries, and command-line tools, while WAR files are used for web applications intended for deployment to a web server. I do not have a general recommendation here because it depends on your use case.
7. Java – The Java version for this project. If using Spring Boot version 3.x.x, the Java version must be 17+.

The Dependency Option

The dependency option allows you to select common dependencies used in Spring Boot projects that will be added to your project’s build.gradle if you are using Gradle, or pom.xml if you are using Maven. Some popular dependencies include:

• Lombok – Lombok provides annotations to reduce boilerplate code in Java classes.
• Spring Web – Spring Web provides functionality to build web applications, including support for RESTful web services and MVC architecture.
• Thymeleaf – Thymeleaf is a server-side template engine that allows for the creation of dynamic web pages by defining templates using HTML.
• Spring Security – Spring Security is a security framework that provides authentication, authorization, and other security features.
• Spring Data JPA – Spring Data JPA provides a simple way to interact with relational databases through the Java Persistence API (JPA) by generating boilerplate code for database operations.

You can start by adding Spring Web if you want to keep things simple. As you build your application, you can add anything else you need.

The Spring Boot Folder Structure

When you extract the zip file created by Spring Initializr, you should end up with a folder structure that looks something like this (if you chose Maven as your build tool, it will look slightly different):

.
└── demo/
    └── demo/
        ├── .gradle/
        │   └── ...
        ├── gradle/
        │   └── ...
        ├── src/
        │   ├── main/
        │   │   ├── java/com/example/demo/
        │   │   │   └── DemoApplication.java
        │   │   └── resources/
        │   │       └── ...
        │   └── test/
        │       └── java/com/example/demo/
        │           └── DemoApplicationTests.java
        ├── .gitignore
        ├── build.gradle
        ├── gradlew
        ├── gradlew.bat
        ├── HELP.md
        └── settings.gradle

If you look carefully, you may notice the outer demo folder contains another folder, also called demo. You can remove the outer folder to simplify the folder structure to:

.
└── demo/
    ├── .gradle/
    │   └── ...
    ├── gradle/
    │   └── ...
    ├── src/
    │   ├── main/
    │   │   ├── java/com/example/demo/
    │   │   │   └── DemoApplication.java
    │   │   └── resources/
    │   │       └── ...
    │   └── test/
    │       └── java/com/example/demo/
    │           └── DemoApplicationTests.java
    ├── .gitignore
    ├── build.gradle
    ├── gradlew
    ├── gradlew.bat
    ├── HELP.md
    └── settings.gradle

Let’s take a moment to understand what these generated files and folders are:

• .gradle/ – This is where Gradle stores its project-specific cache.
• gradle/ – This contains the JAR file and configuration of the Gradle Wrapper.
• src/main/ – This contains the main source code for your application. Initially, it contains one source code file, DemoApplication.java, the entry point for your Spring Boot project, and the resources/ directory, where configuration files, static assets, and HTML templates would be.
• src/test/ – This contains the test code for your application. Initially, it contains one test file, DemoApplicationTests.java, which contains a trivial test.
• .gitignore – This specifies which files and folders should be ignored by Git.
• build.gradle – This is the Gradle build script for your project, which defines your project’s dependencies, plugins, and other build settings.
• gradlew – This is a wrapper shell script that allows you to build your Spring Boot project without already having Gradle on your system.
• gradlew.bat – This is a batch script that does the same thing as gradlew but in the Windows command prompt.
• HELP.md – This is just a markdown file with some references, guides, and additional links. Feel free to delete this file.
• settings.gradle – This is mostly used for multi-project builds. For your Spring Boot project, it will likely just contain the name of your project.

As you can see, most of the files and folders above are from Gradle. If you want to learn more about what these are for, I encourage you to go to the Gradle documentation.

Conclusion

Congratulations! You now have a better understanding of Spring Initializr and how to use it to create Spring Boot applications. You also have an idea of what the various files and folders autogenerated by Spring Initializr do.

Now it is time to open up your favorite text editor or IDE and start coding!