[Spring Boot] Request Body가 계속 Null일 때. Import를 제대로 했나에 대하여.

안녕하세요.

제가 import를 잘 못해서 Request Body를 null로만 받아온 사람으로 보이시나요?

 

맞긴합니다.

지피티가 제가 JSON 데이터와 DTO 매칭 잘 했는지 의심을 계속해서 좀 속상했는데요. 코드를 잘 살펴보니 import를 잘 못했더라구요? 

 

지피티도 못 찾을만한 실수에 대하여 글을 써봅니다.

 

⭐ RequestBody를 사용할 때 발생한 문제와 해결 방법

Spring Boot에서 REST API를 개발할 때 @RequestBody는 클라이언트로부터 JSON 데이터를 객체로 변환하는 데 자주 사용됩니다.

하지만 이 어노테이션을 사용할 때 올바르지 않은 라이브러리를 import하면 의도치 않은 문제가 발생할 수 있습니다.

이번 글에서는
import org.springframework.web.bind.annotation.RequestBody와
import io.swagger.v3.oas.annotations.parameters.RequestBody를
혼동하여 발생한 문제와 이를 해결한 과정을 정리해 보겠습니다.

 

✅ 문제 상황

REST 컨트롤러에서 @RequestBody를 사용해 클라이언트의 요청 데이터를 처리하려 했지만, 계속해서 null 값이 반환되는 문제가 발생했습니다.

예를 들어 다음과 같은 코드가 있다고 가정합니다.

@RestController
@RequestMapping("/api/v1")
public class UserController {

    @PostMapping("/users")
    public ResponseEntity<String> createUser(@RequestBody UserDto userDto) {
        return ResponseEntity.ok("User created: " + userDto.getName());
    }
}

위 코드는 클라이언트가 JSON 데이터를 POST로 전송하면 이를 UserDto 객체로 매핑해야 합니다. 그러나 실행 중 userDto가 항상 null로 반환되었습니다.

 

❗해결 방법

문제를 디버깅하는 과정에서 다음과 같은 사실을 발견했습니다.

@RequestBody 어노테이션을 import할 때 잘못된 패키지를 사용했습니다.

import io.swagger.v3.oas.annotations.parameters.RequestBody; // 잘못된 import

Swagger 관련 어노테이션은 API 문서를 위한 메타데이터를 추가하는 역할을 하며, Spring MVC의 @RequestBody와는 전혀 다른 기능을 합니다.

import org.springframework.web.bind.annotation.RequestBody; // 올바른 import

Spring MVC의 @RequestBody는 다음과 같이 올바른 패키지를 import해야 합니다.

 

🤔 문제 원인 분석 과정

만약 import가 제대로 되었다면 아래 사항들을 확인해보시길 바랍니다!

저는 아래 사항들을 모두 잘 했는데 아무리 해도 null이어서 확인해보니 import 오류였습니다..🥹

1️⃣ JSON 데이터와 DTO 매칭 확인

JSON의 키(name, age)는 DTO 클래스의 필드명과 정확히 일치해야 합니다.
불일치가 있을 경우, 매핑에 실패하거나 일부 필드가 null로 설정됩니다.

2️⃣ JSON 매칭을 위한 어노테이션 추가 

DTO 클래스에 @JsonProperty 또는 @JsonNaming을 사용하여 JSON 데이터와 DTO 필드 간 매칭을 명시적으로 지정할 수 있습니다.

import com.fasterxml.jackson.annotation.JsonProperty;

public class UserDto {
    @JsonProperty("full_name")
    private String name;
    private int age;
}

그럼 아래와 같이 필드명이 name이어도 full_name이라는 키로 JSON을 전달할 수 있습니다.

{
  "full_name": "코양이",
  "age": 30
}

3️⃣ build.gradle 설정 확인 

JSON 매핑은 Jackson 라이브러리를 통해 이루어집니다. Jackson 관련 디펜던시가 누락되었는지 확인하세요.

implementation 'com.fasterxml.jackson.core:jackson-databind:2.15.2' // 예시 버전
implementation 'com.fasterxml.jackson.datatype:jackson-datatype-jsr310' // Java 8 Date/Time 지원

 

💡 교훈과 팁

1) 어노테이션의 역할 명확히 이해하기

• Spring MVC의 @RequestBody: 요청 본문 데이터를 객체로 변환.
• Swagger의 @RequestBody: API 문서 생성용 메타데이터 추가.

두 어노테이션의 역할이 완전히 다르므로 용도에 맞는 패키지를 선택해야 합니다.

2) IDE의 자동 완성 기능 주의하기

IDE에서 자동 완성 기능을 사용할 때 잘못된 패키지가 선택될 수 있습니다. 따라서 import문을 항상 확인하는 습관을 들여야 할 거 같습니다..!

 

📌 결론

Spring Boot와 Swagger를 함께 사용하면서 @RequestBody를 잘못 import해 발생한 문제는 흔히 겪는 실수입니다.

올바른 패키지를 사용하는 것만으로도 문제를 해결할 수 있지만, 이 과정을 통해 어노테이션의 역할과 라이브러리의 특성을 명확히 이해하는 계기가 되었습니다.

위 경험이 같은 문제로 어려움을 겪는 개발자들에게 도움이 되기를 바랍니다. 😊