Swagger와 Postman 간의 드리프트는 프로세스 실패가 아닙니다. 이는 동일한 계약을 두 곳에 저장하고, 이를 동기화하는 메커니즘이 없을 때 발생하는 현상입니다. OpenAPI 스펙을 작성하고, 문서화를 위해 Swagger UI를 지정한 다음, 테스트를 위해 Postman 컬렉션을 내보냅니다. 일주일 후, 누군가 YAML을 건드리지 않고 컬렉션의 엔드포인트를 변경하면, 이제 문서와 테스트는 서로 다른 API를 설명하게 됩니다. 이 글은 그러한 결과가 구조적으로 보장되는 이유와 단일 소스 진실 모델이 실제로 어떻게 작동하는지 설명합니다. 스펙에서 테스트를 생성하는 단계별 방법은 OpenAPI 테스트 생성에 대한 기존 방법 가이드를 참조하십시오.
두 파일이 항상 동기화되지 않는 이유
리포지토리에 openapi.yaml 파일을 유지합니다. 또한 Postman 컬렉션도 유지합니다. 이 두 개체는 동일한 API 계약을 설명하지만, 별도로 저장되고, 다른 사람들에 의해 편집되며, 다른 일정으로 업데이트됩니다. 어떤 도구도 이들 간의 일관성을 강제하지 않습니다.
현실적인 시나리오를 생각해 봅시다. 백엔드 팀은 필수 reason 필드가 포함된 새로운 POST /payments/refund 엔드포인트를 출시합니다. 누군가 테스트를 실행하는 Postman 컬렉션에 이를 추가합니다. openapi.yaml 업데이트는 스프린트 백로그에 들어갑니다. 3일 후, 프런트엔드 개발자는 Swagger 문서를 읽고, reason 없이 엔드포인트를 호출하며, 문서만으로는 설명할 수 없는 400 오류를 받습니다.
근본 원인은 태만이 아닙니다. 이는 두 아티팩트 간의 어떤 바인딩도 없기 때문입니다. 어느 도구도 다른 도구의 존재를 알지 못합니다.
| 아티팩트 | 업데이트 담당자 | 업데이트 트리거 | 유효성 검사 |
|---|---|---|---|
openapi.yaml |
API 설계자 / 기술 리드 | 예정된 문서 스프린트 | 선택적 린터 (예: Spectral) |
| Postman 컬렉션 | QA / 백엔드 개발자 | 테스트 실행 필요 시 | 수동 검토 또는 없음 |
| Swagger UI 보기 | YAML에서 자동 렌더링 | YAML 푸시 시에만 | YAML을 반영하지만, 현실은 반영하지 않음 |
위 표는 문제를 명확하게 보여줍니다. 세 개의 행, 세 명의 다른 업데이트 소유자, 교차 유효성 검사 없음. Spectral과 같은 린터를 YAML에 대해 실행하더라도, 스키마 오류를 잡아낼 뿐, YAML과 완전히 다른 도구에 있는 컬렉션 사이의 간극은 잡아내지 못합니다.
세 개의 복사본 문제
Stoplight와 같은 별도의 문서화 플랫폼을 사용하는 팀은 문제를 더욱 복잡하게 만듭니다. 이제 계약의 세 가지 복사본을 갖게 됩니다.
- Git에 커밋된
openapi.yaml. - 워크스페이스로 내보내지고 공유된 Postman 컬렉션.
- Stoplight (또는 Swagger UI, 또는 위키)에 렌더링된 문서.
각 복사본은 독립적으로 드리프트될 수 있습니다. OpenAPI Specification 자체에는 런타임 강제 메커니즘이 없습니다. 이는 동기화 프로토콜이 아닌 설명 형식입니다. YAML로 원하는 API를 설명할 수 있으며, Postman 컬렉션이 다르게 작동하는 것을 막을 수 없습니다.
이는 세계 경제 포럼의 팀들이 GitHub에 OpenAPI 스펙을 유지하면서 별도의 Postman 컬렉션과 별도의 문서 사이트를 함께 관리할 때 겪는 것과 동일한 압력입니다. 동일한 계약에 대해 세 곳이 존재한다는 것은 세 가지 실패 지점과 세 가지 수동 동기화 루프를 의미합니다. 팀 규모와 여러 서비스가 추가되면 유지보수 비용은 비선형적으로 증가합니다.
드리프트가 테스트를 조용히 망가뜨리는 방법
Swagger와 Postman 드리프트의 교활한 점은 테스트가 잘못되었는데도 계속 통과한다는 것입니다. Postman 컬렉션이 여전히 이전 요청 본문 스키마를 보내고, 테스트 백엔드가 마이그레이션 기간 동안 이전 및 새 스키마를 모두 허용하는 경우, 녹색 테스트 실행은 현재 스펙이 적용되었는지 여부에 대해 아무것도 알려주지 않습니다.
다음은 오래된 Postman 컬렉션을 지나칠 수 있는 스펙 변경을 보여주는 구체적인 YAML 코드 조각입니다.
# openapi.yaml - 업데이트된 스펙 (v2)
paths:
/payments/refund:
post:
summary: Initiate a refund
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- transaction_id
- reason # v2에서 추가된 새로운 필수 필드
properties:
transaction_id:
type: string
example: "txn_8x9Ka21"
reason:
type: string
enum: [duplicate, fraudulent, requested_by_customer]
example: "requested_by_customer"
responses:
'200':
description: Refund initiated
content:
application/json:
schema:
type: object
properties:
refund_id:
type: string
status:
type: string
v1에서 고정된 Postman 컬렉션은 transaction_id만 보냅니다. 백엔드 팀이 배포 중에 reason에 대한 관대한 기본값을 추가하면, 이전 Postman 테스트는 통과합니다. 스펙은 reason이 필수라고 말하지만, 테스트는 이를 전혀 보내지 않습니다. 아무도 프런트엔드 통합이 스테이징에서 깨질 때까지 알아차리지 못합니다.
YAML에 대해 적절한 OpenAPI 유효성 검사 도구를 실행하면 스펙 내의 스키마 불일치를 잡아낼 수 있습니다. 하지만 스펙과 Postman 컬렉션이 실제로 보내는 내용 사이의 간극은 잡아내지 못합니다.
OpenAPI 기반 테스트의 실제 의미
OpenAPI 기반 테스트는 스펙이 신뢰할 수 있는 소스임을 의미합니다. 테스트는 스펙에서 파생되며, 스펙과 병렬적으로 작성되지 않습니다. 스펙이 변경되면, 테스트는 동일한 소스를 공유하기 때문에 변경 사항을 자동으로 반영합니다.
이는 'Swagger를 Postman으로 가져오기'와는 다릅니다. 가져오기는 일회성 복사 작업입니다. 가져오기를 누르면 컬렉션을 얻게 되고, 두 개체는 즉시 다시 독립적이 됩니다. 다음 스펙 변경 시에는 또 다른 수동 가져오기 또는 수동 컬렉션 편집이 필요합니다. 드리프트를 해결한 것이 아니라, 0으로 재설정한 것입니다.
진정한 스펙 우선 실행은 다음과 같습니다.
- OpenAPI 파일은 정식 계약으로 Git에 존재합니다.
- 도구가 해당 파일을 읽고, 모의(mock), 문서, 테스트 케이스를 거기서 파생합니다.
- 파일이 변경되면 (PR 검토를 통해), 모의(mock) 및 테스트 케이스가 업데이트됩니다.
- 동기화할 별도의 컬렉션이 없습니다.
스펙 우선 API 개발 모델은 더 넓은 워크플로우 철학을 설명합니다. 이 글은 문서와 테스트 간의 드리프트라는 특정 문제에 초점을 맞춥니다.
단일 스펙 위에 있는 실행 계층으로서의 Apidog
Apidog의 모델은 Git을 진실의 원천으로, Apidog를 그 위에 있는 실행 계층으로 다룹니다. openapi.yaml을 커밋하면, Apidog는 이를 읽고 해당 단일 파일에서 세 가지 출력물(대화형 문서, 모의 서버, 테스트 스위트)을 생성합니다.
Apidog의 스펙 우선 모드(현재 베타 중)는 정확히 이러한 워크플로우를 위해 설계되었습니다. OpenAPI 파일을 지정하면, 플랫폼은 별도의 컬렉션을 유지 관리할 필요 없이 세 가지 출력물을 모두 파생합니다. YAML을 업데이트하고 푸시하면, 하위 출력물도 업데이트됩니다.
실제 결과는 드리프트될 Postman 컬렉션이 없다는 것입니다. 파일은 하나입니다. OpenAPI 스펙 동기화 워크플로우는 팀이 GitHub에 스펙을 커밋하고 Apidog를 정렬 상태로 유지하는 방법을 다룹니다.
Postman 중심 워크플로우를 사용하던 팀의 경우, 시험 사용 시 다음 사항을 확인해 볼 가치가 있습니다: Apidog가 특정 스키마 복잡성을 가진 데이터 기반 테스트 시나리오를 어떻게 처리하는지, 그리고 보고서 가시성 권한이 조직의 액세스 모델과 일치하는지 여부. 이는 프로덕션 스위트를 마이그레이션하기 전에 고려할 좋은 POC(개념 증명) 질문입니다.
API 모의(mocking) 또한 중요한 부분입니다. 모의가 테스트와 동일한 스펙에서 파생될 때, 모의를 호출하는 프런트엔드 개발자는 테스트가 검증하는 것과 일치하는 응답을 받습니다. 모의가 어디에 적용되는지에 대한 자세한 내용은 API 모의 사용 사례를 참조하십시오.
마이그레이션 경로의 모습
Swagger + Postman 설정에서 전환하는 경우, 마이그레이션은 일거에 모든 것을 대체하는 것이 아닙니다. 합리적인 순서는 다음과 같습니다.
- 현재
openapi.yaml을 Postman 컬렉션과 비교 검토합니다. 스펙에 없는 컬렉션의 모든 엔드포인트와 컬렉션이 다루지 않는 스펙의 모든 엔드포인트를 찾아냅니다. - 스펙을 조정합니다. 처음 YAML을 작성했을 때 존재했던 API가 아니라, 실제 현재 API를 설명해야 합니다.
- 스펙을 Apidog로 가져옵니다. Apidog가 스펙 구조에서 초기 테스트 스위트를 생성하도록 합니다.
- Postman 컬렉션을 점진적으로 폐기합니다. 결과를 비교하기 위해 한 스프린트 동안 두 가지를 병렬로 실행합니다.
- 컬렉션을 보관합니다. Git이 진실의 원천으로 유지됩니다. Apidog가 실행을 처리합니다.
1단계는 보통 가장 불편한 단계인데, 이는 두 아티팩트가 얼마나 멀리 떨어져 있는지 드러내기 때문입니다. 6개월 동안 드리프트가 축적되도록 방치한 팀은 종종 20~40%의 엔드포인트 커버리지 격차를 발견합니다.
스펙에서 초기 테스트 컬렉션을 생성하는 방법은 OpenAPI 스펙에서 테스트 컬렉션 생성에 대한 전용 방법 가이드에서 자세히 다룹니다. 이 글은 의도적으로 그 단계 이전에 멈춥니다. 깔끔한 스펙이 준비되면 생성 튜토리얼이 더 나은 참고 자료가 될 것입니다.
비교: 이중 유지보수 vs. 스펙 기반
| 측면 | Swagger + Postman (이중 유지보수) | OpenAPI 기반 (스펙이 소스) |
|---|---|---|
| 드리프트 위험 | 높음; 두 아티팩트가 독립적으로 업데이트됨 | 낮음; 하나의 아티팩트, 파생된 출력물 |
| 테스트 커버리지 정확성 | 수동 동기화 규율에 따라 달라짐 | 스펙 변경 사항을 자동으로 추적 |
| 신규 개발자 온보딩 | 배우고 정렬해야 할 두 가지 도구 | 하나의 스펙, 하나의 도구가 읽음 |
| CI/CD 통합 | 컬렉션은 별도로 내보내지고 버전 관리되어야 함 | Git의 스펙; CI가 직접 읽음 |
| 모의 일관성 | 모의는 별도로 유지보수되거나 가져와야 함 | 모의는 테스트와 동일한 스펙에서 파생됨 |
| 스키마 변경 비용 | 스펙 업데이트 AND 컬렉션 업데이트 AND 모의 업데이트 | 스펙 한 번 업데이트 |
이중 유지보수 열은 Postman이라는 도구의 실패를 의미하지 않습니다. Postman은 컬렉션 기반 테스트에 강하고 큰 생태계를 가지고 있습니다. 문제는 컬렉션을 파생된 아티팩트가 아닌 병렬 계약으로 취급하는 워크플로우 패턴입니다.
자주 묻는 질문
Swagger를 Postman으로 가져오는 것이 드리프트를 해결하지 못하는 이유는 무엇입니까?
가져오기는 특정 시점의 복사본을 생성합니다. 가져온 후에는 두 개체가 독립적이 됩니다. openapi.yaml에 대한 다음 변경 사항은 컬렉션에 자동으로 전파되지 않습니다. 모든 스펙 변경 시 컬렉션을 다시 가져오거나 수동으로 편집해야 하며, 이는 이중 유지보수 문제로 돌아가게 됩니다.
스펙 우선 모델을 채택하면서도 탐색적 테스트를 위해 Postman을 계속 사용할 수 있습니까?
네, 그렇습니다. 스펙 우선 방식은 애드혹 테스트를 금지하지 않습니다. 자동화된 회귀 테스트 스위트를 스펙 기반 러너로 전환하면서도, 일회성 탐색적 호출을 위해 Postman을 계속 사용할 수 있습니다. 핵심은 탐색적 컬렉션을 계약 유효성 검사를 위한 진실의 원천으로 커밋하지 않는 것입니다.
내 스펙이 실제 API 구현과 달라졌는지 어떻게 알 수 있습니까?
가장 신뢰할 수 있는 확인 방법은 계약 테스트 계층입니다. API 서버는 테스트 시점에 들어오는 요청과 나가는 응답을 OpenAPI 스펙에 대해 검증할 수 있습니다. Spectral과 같은 도구는 스펙의 내부 일관성을 린트하지만, 구현 드리프트를 잡아내려면 런타임 유효성 검사가 필요합니다. 이는 Swagger-Postman 드리프트와는 별개의 문제이지만, 둘 다 존재할 때 문제를 더욱 복잡하게 만듭니다.
Apidog가 Postman을 완전히 대체합니까?
그것은 팀의 워크플로우에 따라 다릅니다. Apidog는 단일 워크스페이스에서 설계, 모의(mocking), 테스트 및 문서를 처리합니다. Postman의 주요 용도가 계약 테스트 및 회귀 스위트인 팀의 경우, Apidog가 해당 영역을 다룹니다. 팀이 CI에서 Postman의 컬렉션 러너를 사용하거나 광범위한 컬렉션 스크립트를 가지고 있다면, 스펙 우선 설계 워크플로우와 함께 Postman을 사용한 테스트는 여전히 옵션으로 남아 있습니다. 시험 스프린트에서 두 가지 모두를 평가해 볼 가치가 있습니다.
내 openapi.yaml이 이미 오래되었다면 어떻게 해야 합니까?
스펙을 조정하는 것이 전제 조건입니다. 지름길은 없습니다. 스펙을 실제 API 동작과 비교하고, YAML을 현실을 반영하도록 업데이트한 다음, 앞으로는 이를 정식 소스로 취급해야 합니다. 위에 제시된 마이그레이션 경로의 감사 단계에서 이 작업이 이루어집니다.
결론
Swagger 문서와 Postman 컬렉션이 드리프트되는 이유는 두 개의 별개 아티팩트로서 서로 간에 바인딩이 없기 때문입니다. 이는 팀 규율 문제가 아니라 이중 유지보수 워크플로우의 구조적 특성입니다. 해결책은 두 번째 아티팩트를 제거하는 것입니다: Git에 하나의 OpenAPI 파일을 두고, 각 아티팩트가 독립적으로 존재하도록 내버려 두지 않고, 그 파일에서 모의(mock), 테스트, 문서를 파생하는 도구를 사용하는 것입니다.
Apidog를 다운로드하고 기존 OpenAPI 스펙을 가져오세요. 단일 세션에서 하나의 파일이 Swagger 문서와 Postman 컬렉션을 모두 대체하며, 모의(mock), 테스트, 문서가 모두 동일한 소스에서 읽히는 방식을 확인할 수 있습니다. 스펙 우선 모드(현재 베타 중)를 평가 중이시라면, Apidog 스펙 우선 모드 페이지에서 현재 기능 범위 및 접근 세부 정보를 확인하십시오.