Swagger와 Postman은 경쟁 관계가 아니다: 차이, 가져오기, 실무 연결 흐름

개념

"둘 중 뭘 써야 하나요"는 잘못된 질문이다

면접에서도 팀 회의에서도 자주 나오는 질문이지만, 전제가 틀렸다. 둘은 같은 일을 다르게 하는 도구가 아니라 서로 다른 구간을 맡는 도구 다.

설계 ──── 구현 ──── 통합 ──── 회귀 ──── 운영 감시
  └──── Swagger (진실의 출처: 계약·문서) ────┘
              └──── Postman (행위 검증: 시나리오·회귀·CI) ────┘

Swagger는 "이 API는 이런 약속이다" 를 한 곳에 고정해두는 쪽이고, Postman은 "그 약속이 실제 상황에서 지켜지는가" 를 반복 실행으로 확인하는 쪽이다. 그래서 문장으로 쓰면 이렇게 된다 — Swagger는 문서가 본업이고 실행은 곁가지, Postman은 실행이 본업이고 문서는 곁가지다.

무엇이 다른가 — 표로 한 번에

왜 Swagger로 테스트를 다 못 하는가 — 구체적으로

"Try it out이 되는데 왜 굳이 Postman을?"에 대한 답은 하나의 시나리오 를 예로 들면 분명해진다.

[회원가입] → [로그인해 토큰 받기] → [장바구니 담기] → [주문 생성]
                                        → [주문 조회로 금액 검증] → [주문 취소]

Swagger UI로 하면 매 단계마다 응답에서 userId, accessToken, cartId, orderId를 손으로 복사해 다음 칸에 붙여 넣어야 한다. 6단계면 복사·붙여넣기가 대여섯 번, 검증은 눈으로, 그리고 내일 다시 하려면 처음부터 전부 다시 한다. 스테이징과 개발 서버에서 두 번 돌리려면 또 두 배다.

Postman은 같은 흐름을 이렇게 바꾼다.

// 로그인 응답에서 토큰을 꺼내 환경 변수에 저장 (Tests 탭)
const body = pm.response.json();
pm.environment.set("accessToken", body.accessToken);
pm.environment.set("orderId", body.orderId);
 
pm.test("주문 금액은 쿠폰 할인이 적용된 값이어야 한다", function () {
  pm.expect(body.totalPrice).to.eql(9000);
});
pm.test("응답은 1초 안에 온다", function () {
  pm.expect(pm.response.responseTime).to.be.below(1000);
});

이후 요청에서 {{accessToken}} 으로 참조하면 복사·붙여넣기가 사라진다. 한 번 만들어두면 실행 한 번으로 6단계가 자동으로 돌고, 판정까지 끝난다. 이것이 모듈 12(레슨 2)에서 배운 컬렉션·어서션의 값어치이고, Swagger UI에는 원래 없는 기능이다 — 없는 게 결함이 아니라, 애초에 문서 도구라서 그렇다.

반대로 Postman이 대체할 수 없는 것

• 항상 최신이라는 보장. Postman 컬렉션은 사람이 만든 사본이라 API가 바뀌어도 자동으로 따라오지 않는다. Swagger는 코드에서 생성되므로 배포 즉시 반영 된다.
• 누구나 링크 하나로 본다. 기획자·협력사·신입이 계정 없이 바로 열어보는 경로는 Swagger 쪽이다.
• 계약의 근거. 모듈 12(레슨 4)의 계약 테스트, 레슨 5의 Pact, 코드 생성(클라이언트 SDK 자동 생성)은 전부 스펙 파일 을 먹고 돌아간다. 컬렉션으로는 그 자리를 채울 수 없다.

실무 흐름 — 팀에서 실제로 어떻게 이어지나

① 백엔드 개발자가 코드에 어노테이션/데코레이터를 달면
   → 빌드할 때 OpenAPI 스펙이 자동 생성되고 Swagger UI가 뜬다
        │
② 프런트엔드·QA가 Swagger를 열어 "주소·필드·인증 방식"을 파악한다
   → 이 단계에서 QA는 스펙 리뷰(필수 필드, 에러 코드, enum)를 한다
        │
③ 단건 확인은 Swagger의 Try it out으로 즉시 끝낸다
        │
④ 로그인이 필요하거나 여러 API를 순서대로 엮어야 하면
   → 스펙을 Postman으로 가져와(Import) 시나리오를 구성한다
        │
⑤ 만든 컬렉션에 어서션을 달아 회귀 테스트 자산으로 승격한다
        │
⑥ Newman으로 CI 파이프라인에 넣어 배포마다 자동 실행한다

요약하면 개발 단계에서는 Swagger를 기본 문서로 깔고 가고, 정밀한 테스트나 프런트엔드 협업이 필요할 때 Postman을 추가로 띄운다. 도구를 고르는 게 아니라 구간에 따라 갈아탄다.

④번을 손으로 하지 않는 법 — 가져오기(Import)

Postman은 OpenAPI 2.0·3.0·3.1을 읽어 폴더·요청·예시 응답이 갖춰진 컬렉션 으로 만들어준다. 스펙 URL(/v3/api-docs)이나 파일을 그대로 넣으면 된다.

주의할 점이 셋 있다.

• 가져오기는 사본을 만드는 것 이다. 그 순간의 스펙을 복제할 뿐, 이후 API가 바뀌어도 컬렉션은 그대로다. Spec Hub의 양방향 동기화를 쓰면 맞출 수 있지만 여러 파일로 쪼개진 스펙은 지원되지 않고, 삭제된 엔드포인트의 요청이 고아로 남는 문제도 있다.
• 자동 생성된 요청은 뼈대일 뿐 이다. 예시 값이 string, 0 같은 자리표시자로 채워져 있어 그대로 돌리면 400이 쏟아진다. 의미 있는 테스트 데이터로 바꾸는 것은 사람 몫이다.
• 매 릴리스마다 손으로 다시 import 하지 않는다. openapi-to-postmanv2(CLI)나 Portman을 CI에 걸어 스펙이 바뀌면 컬렉션을 재생성하도록 만든다. 여기까지 오면 모듈 14에서 배운 "사람이 반복하는 일을 파이프라인에 넘긴다"가 API 테스트에서 완성된다.

⑥번 — Newman으로 CI에 얹기

newman run orders-regression.postman_collection.json \
  -e staging.postman_environment.json \
  --reporters cli,junit \
  --reporter-junit-export results/newman.xml

JUnit XML로 내보내면 GitHub Actions·Jenkins가 테스트 결과를 그대로 읽어 실패한 케이스를 표시한다. Swagger 화면에서 눈으로 보던 검증이 파이프라인의 빨간불로 바뀌는 지점 이 바로 여기다.

실무에서 왜 필요한가

두 도구를 갈라 쓸 줄 알면 "문서가 API와 다르다"는 사고를 구조적으로 줄일 수 있다. 팀이 Postman 컬렉션만 진실로 삼으면 컬렉션을 갱신하지 않은 사람은 옛 API를 테스트하게 되고, Swagger만 믿으면 로그인이 필요한 복합 시나리오는 아무도 반복 검증하지 않는다. 두 축이 각자의 자리를 지킬 때 문서는 최신이고 회귀는 자동으로 돈다.

QA 개인에게는 작업 시간이 직접 줄어든다. 단건 확인에 Postman 컬렉션을 만드는 것은 과잉이고(그냥 Swagger에서 눌러보면 된다), 매 스프린트 반복할 시나리오를 Swagger에서 손으로 돌리는 것은 낭비다. 어느 쪽인지 판단하는 기준은 단순하다 — 두 번 이상 반복할 것인가, 값을 다음 요청으로 넘겨야 하는가. 둘 중 하나라도 예면 Postman이다.

채용시장에서의 위치

API 테스트 관련 채용공고에서 "Postman 사용 경험"은 사실상 기본값이고, "Swagger/OpenAPI 문서 이해"가 함께 요구되는 공고가 계속 늘고 있다. 면접에서 "Swagger와 Postman의 차이가 뭔가요"는 실제로 자주 나오는 질문인데, 기능 나열로 답하면 평범하고 "진실의 출처는 스펙이고 컬렉션은 사본" 이라는 관계로 답하면 설계를 이해한 사람으로 읽힌다.

한 단계 더 얹는다면 Newman·CI 연동 경험이다. 도구를 쓸 줄 아는 사람과 도구의 결과를 파이프라인에 꽂아 팀의 안전망으로 만든 사람 사이에는 연봉 구간이 갈릴 만큼의 차이가 있다.

실습 과제

과제 1 — 스펙을 컬렉션으로 가져오기 (10분)

Postman에서 Import → Link 에 공개 스펙 URL (https://petstore3.swagger.io/api/v3/openapi.json)을 넣어 컬렉션을 만든다. 만들어진 폴더 구조가 Swagger 화면의 태그와 어떻게 대응하는지 확인하고, 자동 생성된 요청 중 그대로 실행하면 실패할 요청 두 개 를 찾아 왜 실패하는지 적는다.

과제 2 — 도구 선택 판단 훈련 (10분)

아래 다섯 상황에서 Swagger UI와 Postman 중 무엇을 쓸지 고르고 한 줄 근거를 적는다.

1. 개발자가 방금 배포한 조회 API가 값을 제대로 주는지 5분 안에 확인
2. 매 스프린트 회귀로 도는 결제 6단계 시나리오
3. 협력사 QA에게 "우리 API 이렇게 생겼습니다"를 전달
4. 토큰 만료 시 재발급이 자동으로 되는지 검증
5. 배포 파이프라인에서 핵심 API 20개가 살아 있는지 매번 확인

과제 3 — 우리 팀 흐름 그리기 (5분)

본문의 6단계 흐름도를 자신이 속한(또는 목표로 하는) 팀 상황에 맞게 다시 그린다. 지금 끊겨 있는 화살표 를 하나 찾아 표시하고, 그것을 잇기 위해 누구에게 무엇을 요청해야 하는지 한 문장으로 적는다.

자가 체크리스트

• Swagger와 Postman의 역할을 "진실의 출처 vs 행위 검증"으로 설명할 수 있다
• Swagger UI로 다단계 시나리오를 검증하기 어려운 이유를 예로 들 수 있다
• OpenAPI 스펙을 Postman 컬렉션으로 가져올 수 있다
• 가져온 컬렉션이 자동으로 최신화되지 않는다는 점과 그 대응책을 안다
• Newman으로 컬렉션을 CI에서 실행하는 명령을 쓸 수 있다
• 단건 확인과 회귀 자산을 구분해 도구를 고를 수 있다

흔한 실수

• Postman 컬렉션을 문서 대신 쓴다. 사본은 반드시 낡는다. 문서의 자리는 스펙이고, 컬렉션은 그 스펙을 실행해보는 도구다.
• 한 번 가져온 컬렉션을 릴리스마다 손으로 다시 만든다. 몇 번은 버티지만 결국 안 하게 된다 — 재생성을 CI로 넘긴다.
• 자동 생성된 요청을 그대로 돌리고 "API가 다 깨졌다"고 보고한다. 자리표시자 값 때문에 400이 나는 것과 진짜 결함은 다르다.
• 어서션 없는 컬렉션을 회귀 테스트라고 부른다. 실행만 되고 판정이 없으면 사람이 매번 눈으로 봐야 하므로 자동화가 아니다.
• 모든 것을 Postman으로 옮기려 한다. 조회 API 하나 확인하는 데 컬렉션·환경·변수를 만드는 것은 명백한 과잉이다.
• 인증 처리를 컬렉션마다 복사한다. 컬렉션 수준 Authorization과 pre-request script로 토큰 발급을 한 곳에 모아야 유지된다.

참고 자료

• Import an API specification — Postman Docs — OpenAPI 2.0·3.0·3.1 가져오기
• Generate collections from your API specification — Postman Docs — 스펙 ↔ 컬렉션 동기화와 그 한계
• openapi-to-postman (GitHub) — 컬렉션 재생성 자동화용 CLI
• Swagger vs. Postman — Swagger 블로그 — 두 도구의 역할 구분에 대한 공식 관점