Swagger에서 curl 명령 올바르게 해석하기

개발 과정에서 API 문서화 도구인 Swagger를 활용할 때, curl 명령어를 제대로 이해하지 못해 발생한 실수와 그 해결책에 대해 알아봅니다.

문제 상황

React Native 프로젝트에서 JWT 토큰 갱신 기능을 구현하던 중 발생한 문제였습니다.
백엔드 API는 제대로 동작하고 있었지만, 프론트엔드에서 토큰 갱신 요청이 계속 실패했습니다.

서버에서 제공한 Swagger 문서에는 다음과 같은 curl 명령어가 예시로 제공되었습니다:

curl -X 'POST' \
'http://13.125.58.70:8080/auth/refresh' \
-H 'accept: */*' \
-H 'Refresh-Token: eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0ZXN0MTIzNEBnbWFpbC5jb20iLCJ1c2VySWQiOjMwLCJqdGkiOiJmYWJhZDEzNi1jYzk2LTRhZjktOTEwOS05YjUzNWFhMDJhZWMiLCJleHAiOjE3NDE5MzI2NDcsImlhdCI6MTc0MDcyMzA0N30.NU3EiD3yZUW79ODuQQkd-XrF0wPN1tMuvHT-ThhGwGY' \
-d ''

반면, 제가 작성한 axios 코드는 다음과 같았습니다:

const response = await refreshAxios.post("/auth/refresh", null, {
  headers: { refreshToken },
});

문제의 원인

curl 명령어와 axios 요청의 차이점을 자세히 살펴보면 명백한 문제가 보입니다:

1. curl에서는 헤더 이름이 Refresh-Token
2. 제 코드에서는 헤더 이름이 refreshToken

이 작은 차이가 API 요청이 실패하는 결정적인 원인이었습니다.

해결책

axios 요청에서 헤더 이름을 올바르게 수정했습니다:

const response = await refreshAxios.post("/auth/refresh", null, {
  headers: { "Refresh-Token": refreshToken },
});

이렇게 수정한 후에는 토큰 갱신 요청이 정상적으로 동작했습니다.

curl 명령어 제대로 읽기

curl 명령어를 제대로 해석하지 못해 발생한 이 문제를 통해 배운 점을 정리해 보겠습니다.

curl 명령어 형식 이해하기

curl [옵션] [URL]

• -X: HTTP 메소드 지정 (GET, POST, PUT, DELETE 등)
• -H: HTTP 헤더 지정
• -d: HTTP 요청 본문(body) 데이터 지정

헤더 형식 이해하기

-H '헤더이름: 헤더값'

curl 명령에서 -H 옵션 다음에 오는 '헤더이름: 헤더값' 형식을 정확히 파악해야 합니다. 헤더 이름은 대소문자를 구분하며, 대시(-)가 포함된 경우도 있습니다.

Swagger에서 curl 예제 활용하기

Swagger에서 제공하는 curl 예제는 API 요청을 정확하게 구성하는 데 매우 유용합니다:

1. HTTP 메소드 확인: -X 'POST'와 같은 부분에서 어떤 메소드를 사용해야 하는지 확인
2. 엔드포인트 URL 확인: 전체 URL 구조 파악
3. 필요한 헤더 확인: -H 옵션 뒤에 오는 헤더들을 정확히 확인
4. 요청 본문 확인: -d 옵션 뒤에 오는 데이터 형식 확인

axios로 변환하기

curl 명령을 axios 요청으로 변환할 때 주의해야 할 점:

1. URL 설정: baseURL과 엔드포인트 경로 구분
2. HTTP 메소드 설정: axios.get(), axios.post() 등 올바른 메소드 사용
3. 헤더 설정: 헤더 이름과 값을 정확히 일치시키기
4. 요청 본문 설정: axios의 두 번째 파라미터로 요청 본문 전달

curl에서 axios로 변환 예시

curl -X 'POST' \
'http://example.com/api/resource' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer token123' \
-d '{"name":"value"}'

위 curl 명령은 다음과 같이 axios로 변환됩니다:

axios.post('http://example.com/api/resource', 
  { name: 'value' },
  {
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer token123'
    }
  }
);

결론

API 개발 시 Swagger와 같은 문서화 도구에서 제공하는 예제는 매우 중요한 참고 자료입니다.
특히 curl 명령어는 API 요청의 모든 세부사항을 담고 있으므로, 이를 정확히 해석하여 코드로 구현하는 능력이 필요합니다.

이번 경험을 통해 작은 차이(헤더 이름의 대소문자와 하이픈)가 API 통신에 큰 영향을 미칠 수 있다는 것을 다시 한번 깨달았습니다. 문제 해결 과정에서 디버깅 능력도 향상되었고, curl 명령어와 HTTP 프로토콜에 대한 이해도 깊어졌습니다.

다음에 비슷한 상황이 발생하면 Swagger에서 제공하는 curl 예제를 더 꼼꼼히 살펴보고, 헤더 이름과 형식을 정확히 일치시키는 것이 중요하다는 것을 기억하겠습니다.