Introduction

In Spring MVC, @Controller and @RestController are both controller annotations, but they serve different default response models. @Controller is primarily for MVC endpoints that return views, while @RestController is for endpoints that return response bodies directly, usually as JSON.

What @Controller means

@Controller marks a class as a Spring MVC controller whose methods typically resolve to view names.

1import org.springframework.stereotype.Controller;
2import org.springframework.ui.Model;
3import org.springframework.web.bind.annotation.GetMapping;
4
5@Controller
6public class GreetingController {
7
8    @GetMapping("/greeting")
9    public String greeting(Model model) {
10        model.addAttribute("message", "Hello World");
11        return "greeting";
12    }
13}

Here the return value is the name of a view template, not raw response data.

This is the right model for server-rendered pages with Thymeleaf, JSP, or another view technology.

What @RestController means

@RestController is effectively @Controller plus @ResponseBody applied by default to handler methods.

1import java.util.Map;
2import org.springframework.web.bind.annotation.GetMapping;
3import org.springframework.web.bind.annotation.RestController;
4
5@RestController
6public class ApiController {
7
8    @GetMapping("/data")
9    public Map<String, String> data() {
10        return Map.of("key", "value");
11    }
12}

Spring serializes the return value into the HTTP response body through message converters.

That is why @RestController is the normal choice for JSON APIs.

The default-behavior difference

The main difference is not that one can handle requests and the other cannot. Both can handle requests. The difference is what Spring assumes you mean by the return value.

• with @Controller, a returned string is usually treated as a view name
• with @RestController, a returned value is written to the response body

That default changes how concise your code can be and what kinds of endpoints the controller is meant to represent.

Mixing behaviors with @Controller

You can still return response bodies from a plain @Controller by adding @ResponseBody on individual methods.

1import java.util.Map;
2import org.springframework.stereotype.Controller;
3import org.springframework.web.bind.annotation.GetMapping;
4import org.springframework.web.bind.annotation.ResponseBody;
5
6@Controller
7public class MixedController {
8
9    @GetMapping("/page")
10    public String page() {
11        return "home";
12    }
13
14    @GetMapping("/api/info")
15    @ResponseBody
16    public Map<String, String> info() {
17        return Map.of("status", "ok");
18    }
19}

This is useful when one controller legitimately mixes page rendering and API output, though many teams prefer to separate those concerns into different classes.

When to choose each one

Use @Controller when:

• you are rendering HTML views on the server
• your return values represent template names
• you are following an MVC page-based architecture

Use @RestController when:

• you are building REST-style endpoints
• you want JSON or XML responses written directly
• the controller exists to expose data rather than render templates

Why this matters in debugging

A very common confusion happens when someone returns a string from a @Controller expecting raw text, but Spring interprets it as a view name. Switching to @RestController, or adding @ResponseBody, changes the meaning of that return value.

This is why two controllers can look structurally similar in code while producing completely different runtime behavior from the exact same Java return type.

That single misunderstanding explains a surprising number of “why is Spring trying to resolve a template named ok” issues.

Common Pitfalls

A common mistake is using @Controller for an API and forgetting @ResponseBody, which causes return values to be treated as view names.

Another mistake is using @RestController for a server-rendered page flow where you actually wanted template rendering.

A third mistake is thinking the annotations define business logic differences when the real distinction is response handling semantics.

Summary

• '@Controller is aimed at MVC controllers that usually return views.'
• '@RestController is aimed at endpoints that return response bodies directly.'
• '@RestController acts like @Controller plus @ResponseBody by default.'
• Use @Controller for template rendering and @RestController for JSON-style APIs.
• The difference mainly affects how Spring interprets handler return values.