Short version for the busy and the slightly dramatic

Quick summary for impatient developers

• Use @Controller when you want server side rendering with JSP Thymeleaf or another template engine and methods return view names that a view resolver will turn into HTML
• Use @RestController when you want objects serialized to JSON XML or other formats for APIs and clients like SPAs mobile apps or other services
• @RestController is just @Controller plus @ResponseBody so Spring bypasses view resolution and hands your object to HttpMessageConverters for serialization

Controller and RestController in action

Think of @Controller as the traditional stage actor that hands off a scene to a view resolver and asks the template to do the heavy lifting. Think of @RestController as the actor who posts raw data to the feed and leaves the rendering drama to the client.

@Controller
public class PageController {
    @GetMapping("/home")
    public String home(Model model) {
        model.addAttribute("name", "Guest");
        return "home";
    }
}

The controller example returns a string that maps to a template like home html which the view resolver finds and renders. This is server side rendering pure and simple.

@RestController
public class ApiController {
    @GetMapping("/users")
    public List list() {
        return userService.findAll();
    }
}

The RestController example returns a List of User objects which Spring converts to JSON using message converters. No view resolver involved unless you really try to make it sad.

What actually happens under the hood

When a method is annotated with @ResponseBody or the class is @RestController Spring skips view resolution and uses HttpMessageConverter instances to write the response. That means content negotiation for JSON XML or other formats works automatically based on Accept headers and available converters. Status codes headers and content type handling still work the same way so you can use ResponseEntity to control status and headers when you need to be explicit.

Useful rules of thumb

• Server side rendered pages use @Controller and return template names
• APIs use @RestController and return domain objects or ResponseEntity objects so clients get JSON or XML
• If you only need one method to return JSON add @ResponseBody to that method otherwise switch the whole class to @RestController for brevity and fewer surprises
• Avoid returning view names from methods in a RestController unless you are trying to confuse future you

Common gotchas and quick fixes

• If your page suddenly comes back as JSON you probably converted a controller to rest without changing a template return. Change the annotation or the return type and move on
• If you need custom serialization control the converters or return ResponseEntity and set headers and status manually
• Mixing both approaches in one class is possible but messy. Keep intent explicit to avoid accidental HTML in JSON responses

Final thought no magic here just intent. Use @Controller for pages and @RestController for APIs and your code will be easier to read debug and explain to the intern next quarter. Now go pick the one that matches your use case and stop arguing about annotations in meetings.