Spring MVC – Mapping the Root URL to a Page

Last updated: January 8, 2024

Written by: Abhinav Pandey

Reviewed by: Saajan Nagendra

Spring MVC

Spring Annotations

Refactor Java code safely — and automatically — with OpenRewrite.

Refactoring big codebases by hand is slow, risky, and easy to put off. That’s where OpenRewrite comes in. The open-source framework for large-scale, automated code transformations helps teams modernize safely and consistently.

Each month, the creators and maintainers of OpenRewrite at Moderne run live, hands-on training sessions — one for newcomers and one for experienced users. You’ll see how recipes work, how to apply them across projects, and how to modernize code with confidence.

Join the next session, bring your questions, and learn how to automate the kind of work that usually eats your sprint time.

1. Overview

In this tutorial, we’ll see how to map the root URL to a page in Spring MVC.

First, we’ll look at the default behavior of Spring MVC. Then, we’ll discuss a scenario where this behavior gets suppressed. Finally, we’ll learn ways to provide our own custom mapping.

2. Project Setup

We can use Spring Initializr to generate the project while adding the Spring Web Starter dependency.

If adding the dependency manually, we’ll need to add the following to the pom.xml file:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

2.1. Creating the Index Page

Let’s create a page in the src/main/resources/templates folder. We’ll name this page index.html:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Index Page</title>
</head>
<body>
    <h1>Hello World!</h1>
</body>
</html>

2.2. Default Behavior

Let’s run the application and see the default behavior of Spring MVC.

Once the application is up and running, let’s navigate to the root URL: http://localhost:8080/:

Index page loads fine and hello world is displayed

As we can see, the index page is displayed without any need for mapping.

3. Changing the Default Behavior

Let’s look at a scenario where the default behavior gets suppressed.

3.1. @EnableWebMvc

Let’s add the @EnableWebMvc annotation to our RootMappingApplication class:

@SpringBootApplication
@EnableWebMvc
public class RootMappingApplication {
    public static void main(String[] args) {
        SpringApplication.run(RootMappingApplication.class, args);
    }
}

Let’s run the application and navigate to the root URL: http://localhost:8080/. This time, we get an error:

An error page is displayed showing 404-Not Found error

This is because the @EnableWebMvc annotation disables the automatic web app configuration done by Spring Boot.

To fix this, we’ll need to provide our own custom mapping. Let’s look at the different ways to do this.

4. Custom Mapping

Let’s look at the different ways to provide our own custom mapping.

4.1. Using a Controller

One way to provide a path and file mapping is by using a controller.

Let’s start by creating a controller class:

@Controller
public class RootController {
    @GetMapping("/")
    public String index() {
        return "index";
    }
}

This controller class has a single method mapped to the “/” path. The method simply returns the string “index“. When interpreting the return value, Spring MVC looks for a template with the same name in the src/main/resources/templates folder.

If we run the application and navigate to the root URL: http://localhost:8080/, we’ll see the index page displayed.

This is a simple way to provide a custom mapping. It’s fine to use this method when we have a single page to map. However, if we have multiple pages to map, this method can become cumbersome.

Let’s look at a more efficient way to provide a custom mapping.

4.2. Using WebMvcConfigurer

Another way to provide a path and file mapping is by using the WebMvcConfigurer interface.

Let’s start by creating a configuration class:

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addViewControllers(ViewControllerRegistry registry) {
        registry.addViewController("/").setViewName("index");
    }
}

This configuration class implements the WebMvcConfigurer interface. It overrides the addViewControllers() method to add a view controller. The view controller is mapped to the “/” path and returns the “index” view.

Again, if we run the application and navigate to the root URL: http://localhost:8080/, we’ll see the index page.

We should note that if both a controller and a configuration provide mappings for the same path, the controller takes precedence.

5. Conclusion

In this article, we saw how to map the root URL to a page in Spring MVC. We discussed the default behavior of Spring MVC and how it’s overridden by a custom configuration.

We’ve also looked at two ways to provide our own custom mapping – by using a controller and by using the WebMvcConfigurer interface.

The code backing this article is available on GitHub. Once you're logged in as a Baeldung Pro Member, start learning and coding on the project.