[Postman] API access token 자동화하기

프로젝트 할 때 마다 Postman으로 테스트할 때 로그인하고 Authorization 필요한 api마다 하나하나 access token 값 긁어 넣는 게 너무너무 귀찮아서 찾아보다가 알게됐다 Swagger 사용할거라면 상관없긴 하지만 직전의 프로젝트에서는 Swagger를 사용하지 않기로 결정했었기 때문에 어쩔 수 없었다

 

0. Swagger를 사용하지 않은 이유

[1] 런타임 환경의 오염 (Dependency & Security)

: Swagger는 애플리케이션이 실행 중(Runtime)일 때 함께 구동됨

• 라이브러리 침투: Swagger 라이브러리가 프로젝트의 의존성에 포함되어 실제 서버 메모리를 점유하고 구동 환경에 영향을 줌
• 보안 취약점: 설정 실수로 운영(Production) 환경에서 Swagger UI가 노출될 경우, API 구조는 물론 테스트 호출 기능을 통해 실데이터가 유출되거나 조작될 위험이 있음
• 반면 RestDocs는: 빌드 시점에 문서(정적 파일)를 만들고 빠짐. 실제 서버가 돌아갈 때는 문서화 관련 코드가 아예 동작하지 않으므로 런타임 환경이 순수하게 유지됨

[2] 테스트 데이터와 실데이터의 혼재

: Swagger의 가장 큰 장점인 'Try it out' 기능이 역설적으로 데이터 오염의 원인이 됨

• 개발자가 문서를 보다가 무심코 'Execute' 버튼을 눌러 운영 DB나 공용 개발 DB에 테스트 데이터를 박아넣게 될 수도 있음
• RestDocs: RestDocs는 기본적으로 '읽기 전용' 문서라서 데이터를 직접 날려볼 수 없기 때문에, 문서 확인 과정에서 실수로 DB 상태를 변경할 리스크가 원천 차단됨

[3] 비즈니스 로직의 가독성 저해

• 클린 코드 관점에서 컨트롤러는 비즈니스 흐름을 보여줘야 하는데 Swagger를 쓰면 코드의 70~80%가 문서용 설정값으로 채워짐
  • @ApiOperation, @ApiResponse 등 로직과 상관없는 코드가 실제 비즈니스 코드보다 길어지는 경우가 많음
• 진짜 중요한 로직(Validation, Service Call 등)이 문서용 코드에 파묻혀 버려, 유지보수 시 가독성이 떨어지고 버그를 찾기 어려워짐

[4] 문서의 신뢰도 (테스트 통과 필수)

: 문서와 실제 API가 따로 노는 현상을 방지할 수 있음

• Swagger: 코드를 수정하고 어노테이션을 업데이트하지 않아도 서버는 잘 돌아감. 수정된것에 대한 확인이 수동임
• RestDocs: API 테스트가 성공해야만 문서가 생성됨. 기능이 바뀌었는데 테스트를 수정하지 않으면 빌드 자체가 실패하므로, 문서는 항상 최신 상태와 정확성을 보장받음

근데 이렇게 해두고 정작 Spring Rest Docs는 아직 못 써봤다ㅋㅋㅋㅋ 프론트엔드 없는 프로젝트라서 큰 문제는 없었지만

 

1. 적용방법

Postman Scripts

• Postman의 Scripts(또는 Tests) 탭에 코드를 작성하면, API 응답이 올 때 특정 값을 추출해 Postman의 전역 변수(Globals)에 자동으로 저장할 수 있음.

CASE A: Access Token만 받는 경우

서버 응답 JSON의 키값이 access_token인 경우임.

// 1. 응답 성공 여부 확인
pm.test("Status code is 200", function () {
    pm.response.to.have.status(200);
});

// 2. JSON 데이터 파싱
const jsonData = pm.response.json();

// 3. 토큰 추출 및 전역 변수 저장
// 서버 응답 키가 access_token인지 accessToken인지 확인 필수
const token = jsonData.access_token || jsonData.accessToken;

if (token) {
    pm.globals.set("access_token", token);
    console.log("✅ Access Token 저장 완료");
}

CASE B: Refresh Token까지 함께 받는 경우

두 토큰을 모두 저장하여 나중에 토큰 재발급 API에서도 활용할 수 있음.

const jsonData = pm.response.json();

// Access Token 저장
const accessToken = jsonData.access_token || jsonData.accessToken;
if (accessToken) {
    pm.globals.set("access_token", accessToken);
}

// Refresh Token 저장
const refreshToken = jsonData.refresh_token || jsonData.refreshToken;
if (refreshToken) {
    pm.globals.set("refresh_token", refreshToken);
    console.log("✅ Access & Refresh Token 모두 저장 완료");
}

---

3. 전체 적용 과정

1. 로그인 API 설정: 로그인(또는 토큰 발급) API의 Scripts 탭에 위 코드를 붙여넣고 저장함
2. API 실행: Send 버튼을 눌러 로그인 요청을 보냄. 하단 Console 창에 "저장 완료" 로그가 뜨는지 확인함
3. 변수 확인: 오른쪽 상단 가로선 여러개(variables) 아이콘을 클릭해 Globals 항목에 토큰 값이 잘 들어왔는지 확인함.
4. 다른 API에서 사용:
   • 토큰이 필요한 API의 Authorization 탭으로 이동함.
   • Auth Type을 Bearer Token으로 선택함.
   • Token 필드에 직접 입력 대신 {{access_token}}을 입력함. (글자 색이 주황색으로 변해야 정상임)

---

4. 응답 구조가 바뀔 때 대처법 (Troubleshooting)

만약 서버 개발자가 응답 JSON 구조를 바꾸면 코드의 추출 경로를 수정해야 함.

• 키 이름이 바뀐 경우:
  • jsonData.access_token → jsonData.data.token 등으로 경로를 수정함.
• 변수가 빨간색으로 뜨는 경우:
  • pm.globals.set("이름", ...)에서 설정한 이름과 {{이름}}에 적은 이름이 대소문자까지 일치하는지 확인함.
• 값이 안 잡히는 경우:
  • Postman 좌측 하단 Console을 열어 에러 메시지를 확인하고, pm.response.json()으로 들어오는 실제 데이터 구조를 파악함.

 

6. 결론

이 설정을 마치면 로그인 API 호출 한 번으로 모든 테스트 준비가 끝남!

 

---

 

7. 추가로 해볼 것

근데 필요 권한이 다른 api들을 재 로그인 없이 이어서 테스트하고 싶을 때 (예를 들면, customer로 주문을 생성하고, 직후에 master가 모든 customer에 대한 전체 주문을 확인하는 경우) 에는 환경변수를 분리해서 받아야 하니까... 

로그인한 사용자가 관리자(MANAGER/ADMIN)인지 일반 사용자(USER)인지에 따라 변수 이름을 다르게 저장하면, 여러 계정의 토큰을 번갈아 가며 테스트할 때 훨씬 편해질것같은데

(아래는 직접 해보지 않은... 초안? 같은겁니다)

1. Role이 String인 경우

• 서버 응답 JSON에서 role 값이 "ADMIN", "USER" 등 Enum이 아닌 문자열로 바로 오는 경우

const jsonData = pm.response.json();
const token = jsonData.access_token || jsonData.accessToken;
const role = jsonData.role; // 예: "ADMIN", "USER", "MANAGER"

if (token && role) {
    // role 값을 소문자로 변환하여 변수명 생성 (예: admin_token, user_token)
    const variableName = `${role.toLowerCase()}_token`;
    
    pm.globals.set(variableName, token);
    console.log(`✅ ${role} 권한 토큰이 {{${variableName}}}에 저장됨`);
}

---

2. Role이 Enum인 경우 (객체 구조 대응)

일반적으로 Java(Spring Boot) 등에서 Enum을 사용하면, 응답이 단순 문자열이 아니라 { "key": "ADMIN", "name": "관리자" } 식의 객체 형태로 내려올 때가 많음. 이를 고려한 코드임

const jsonData = pm.response.json();
const token = jsonData.access_token || jsonData.accessToken;

// Role이 객체인 경우와 문자열인 경우 모두 대응
let roleValue;
if (typeof jsonData.role === 'object' && jsonData.role !== null) {
    roleValue = jsonData.role.key || jsonData.role.code; // Enum의 필드명에 맞춰 수정 (key 또는 code)
} else {
    roleValue = jsonData.role;
}

if (token && roleValue) {
    const variableName = `${roleValue.toLowerCase()}_token`;
    
    pm.globals.set(variableName, token);
    console.log(`✅ Enum 기반 ${roleValue} 토큰이 {{${variableName}}}에 저장됨`);
}

 

이렇게 Role별로 저장하면 API 테스트를 할 때 Authorization 설정을 유연하게 바꿀 수 있을 듯

• 관리자 API 테스트 시: {{admin_token}} 사용
• 일반 유저 API 테스트 시: {{user_token}} 사용

 

일단 지금은 로그인 시 access token만 리턴해서, role에 대한 정보가 없어서 이렇게만 적었다

나중에 해보고 추가할지도