Postman 컬렉션과 OpenAPI 스펙의 불일치는 팀이 커질수록 자주 발생합니다. 6개월 전에 만든 컬렉션을 다시 열어보면 필수 필드가 추가되어 있고, 일부 매개변수는 더 이상 사용되지 않으며, 응답 예시는 실제 서버 응답과 맞지 않을 수 있습니다. 반면 Git의 OpenAPI 스펙은 다른 내용을 말하고, Swagger UI도 또 다른 상태를 보여줍니다. 문제는 “어떤 문서가 진짜인가?”입니다.
이 불일치는 Postman 자체의 실패가 아니라 워크플로우의 실패입니다. Postman은 요청 실행, 스크립팅, 탐색적 테스트에 강합니다. 하지만 컬렉션을 API 계약 자체로 취급하면 문제가 생깁니다. 컬렉션은 계약에서 파생된 실행용 아티팩트여야 하며, 계약의 원본은 OpenAPI 스펙이어야 합니다.
💡 종속성 방향을 바꾸면 불일치가 줄어듭니다. 컬렉션이 스펙을 만드는 것이 아니라, 스펙이 컬렉션을 생성해야 합니다. Apidog는 이 스펙 중심 워크플로우를 협업, 모킹, 테스트, CI/CD와 연결하여 팀이 동일한 API 계약을 기준으로 작업할 수 있게 합니다.
컬렉션이 애초에 불일치하는 이유
Postman 컬렉션은 요청 우선 아티팩트입니다. 요청을 보내고, 응답을 관찰하고, 저장합니다. 이후 사전 요청 스크립트, 변수, 테스트 어설션, 폴더 구조를 추가하면서 “팀이 API를 호출하는 방식”을 담게 됩니다.
반면 OpenAPI 스펙은 계약 우선 아티팩트입니다. 경로, 매개변수, 요청/응답 스키마, 상태 코드, 인증 방식 등을 기계가 읽을 수 있는 형식으로 정의합니다. 이 스펙은 검증, 모킹, 문서화, 코드 생성, 테스트 생성의 입력으로 사용할 수 있습니다.
두 아티팩트는 서로 다른 질문에 답합니다.
- Postman 컬렉션: “오늘 이 엔드포인트를 어떻게 호출하나요?”
- OpenAPI 스펙: “이 API는 무엇을 보장해야 하나요?”
팀이 둘을 독립적으로 관리하면 불일치는 필연적입니다. 한 개발자는 PR에서 스펙을 수정하고, 다른 개발자는 테스트 실패를 보고 컬렉션만 수정합니다. 둘을 자동으로 동기화하지 않으면 몇 달 뒤에는 동일한 API에 대한 두 개의 부분적으로만 정확한 설명이 남습니다.
인벤티스 코리아도 비슷한 문제를 겪었습니다. API를 만들고, Swagger용 OpenAPI 스펙을 생성하고, 테스트를 위해 Postman 컬렉션으로 가져온 뒤, 세 가지 표현을 계속 동기화해야 했습니다. 컬렉션이 전체 스키마를 반영하지 않아 테스트가 엣지 케이스를 놓쳤고, 스펙이 테스트 생성의 입력이 아니어서 문서도 불일치했습니다.
근본 원인: Postman은 스펙 저장소로 설계되지 않았습니다
Postman 컬렉션은 자체 JSON 형식을 사용합니다. Postman 컬렉션 스키마는 요청, 스크립트, 폴더 계층을 표현합니다. 하지만 이것은 OpenAPI가 아닙니다.
Postman은 OpenAPI를 가져오고 내보낼 수 있지만, 양방향 변환에는 손실이 있습니다.
- OpenAPI → Collection: 요청으로 표현하기 어려운 스키마 세부 정보가 누락될 수 있습니다.
- Collection → OpenAPI: 스크립트, 테스트 데이터, 일부 실행 컨텍스트는 스펙 필드로 표현되지 않습니다.
단일 엔드포인트를 기준으로 비교하면 차이가 명확합니다.
| 속성 | Postman 컬렉션 | OpenAPI 스펙 |
|---|---|---|
| 요청 매개변수 | 키-값 쌍으로 저장됨 |
required, schema로 유형화 및 검증 |
| 응답 형태 | 저장된 예시로 캡처됨 | JSON Schema로 정의되고 $ref 재사용 가능 |
| 오류 응답 | 요청별로 수동 추가 |
responses에 상태 코드별로 정의 |
| 스키마 재사용 | 요청 간 복사-붙여넣기 |
components/schemas와 $ref 사용 |
| 기계 판독 가능한 계약 | 제한적 | 예 |
| Git diff | 불투명한 JSON ID 때문에 리뷰 어려움 | YAML 기반 줄 단위 diff 가능 |
| 린트 및 유효성 검사 | 네이티브 형식에서는 제한적 | Spectral, Redocly CLI 등 사용 가능 |
핵심은 컬렉션이 API 계약을 완전히 표현하기 어렵다는 점입니다. 따라서 계약은 OpenAPI 스펙에 두고, 컬렉션은 그 계약에서 생성해야 합니다.
Postman 팀에게 스펙 우선 방식이 의미하는 것
스펙 우선 방식은 “코드를 한 줄도 쓰기 전에 모든 API를 YAML로 완벽하게 설계하라”는 뜻이 아닙니다.
컬렉션 중심 워크플로우에서 마이그레이션하는 팀에게는 보통 다음을 의미합니다.
- OpenAPI 스펙을 API의 권위 있는 설명으로 Git에 저장합니다.
- 테스트, 문서, 목 서버, Postman 컬렉션은 스펙에서 생성합니다.
- API가 변경되면 스펙을 먼저 수정합니다.
- 다운스트림 아티팩트는 자동 생성 또는 동기화합니다.
스펙 우선 방법론의 핵심은 컬렉션을 없애는 것이 아니라, 컬렉션의 위치를 바꾸는 것입니다.
실제 워크플로우는 다음과 같습니다.
- OpenAPI 스펙을 Git에 커밋합니다.
- PR에서 스펙 변경을 리뷰합니다.
- CI에서 스펙을 린트하고 검증합니다.
- 검증된 스펙에서 Postman 컬렉션을 생성합니다.
- 생성된 컬렉션으로 Newman 또는 Postman CLI 테스트를 실행합니다.
- 문서와 목 서버도 동일한 스펙에서 생성합니다.
이렇게 하면 컬렉션이 더 이상 스펙의 업스트림이 아닙니다. 컬렉션은 스펙의 다운스트림 결과물입니다.
스펙에 필드가 추가되면 생성된 컬렉션에도 반영됩니다. 스펙에서 필드가 제거되면 생성된 요청에서도 사라집니다. 불일치는 6개월 뒤 사람이 발견하는 문제가 아니라, CI에서 즉시 감지되는 실패가 됩니다.
스펙에서 컬렉션을 생성하는 방법
OpenAPI 스펙에서 Postman 호환 컬렉션을 생성하는 방법은 여러 가지가 있습니다. 아래 예시는 Redocly CLI와 openapi-to-postmanv2를 사용하는 방식입니다.
# Redocly CLI 설치
npm install -g @redocly/cli
# OpenAPI 스펙 검증
redocly lint openapi/petstore.yaml
# $ref 체인을 해석하여 번들 생성
redocly bundle openapi/petstore.yaml -o dist/petstore-bundled.yaml
# openapi-to-postmanv2 설치
npm install -g openapi-to-postmanv2
# Postman collection v2.1 생성
openapi2postmanv2 \
--spec dist/petstore-bundled.yaml \
--output dist/petstore-collection.json \
--prettyPrint
출력 파일은 표준 Postman 컬렉션 JSON입니다.
dist/petstore-collection.json
이 파일은 다음 방식으로 사용할 수 있습니다.
- Postman UI로 가져오기
- Newman으로 실행
- Postman CLI에서 실행
- CI 테스트의 입력으로 사용
사전 요청 스크립트와 환경 변수는 별도 파일로 유지하는 것이 좋습니다. 스펙에서 컬렉션을 재생성할 때 요청 구조는 갱신되지만, 환경별 설정은 별도로 관리할 수 있습니다.
GitHub Actions에서 자동화하기
테스트 실행 전에 항상 스펙에서 컬렉션을 재생성하도록 CI에 연결할 수 있습니다.
# .github/workflows/api-tests.yml
name: API contract tests
on:
push:
paths:
- "openapi/**"
- "src/**"
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install dependencies
run: |
npm install -g @redocly/cli openapi-to-postmanv2 newman
- name: Validate OpenAPI spec
run: redocly lint openapi/petstore.yaml
- name: Generate collection from spec
run: |
mkdir -p dist
redocly bundle openapi/petstore.yaml -o dist/petstore-bundled.yaml
openapi2postmanv2 \
--spec dist/petstore-bundled.yaml \
--output dist/petstore-collection.json \
--prettyPrint
- name: Run tests against generated collection
run: |
newman run dist/petstore-collection.json \
--environment config/env-staging.json \
--reporters cli,junit \
--reporter-junit-export results/test-results.xml
- name: Upload test results
uses: actions/upload-artifact@v4
with:
name: test-results
path: results/
이 패턴의 장점은 명확합니다.
- 스펙이 모든 테스트 실행의 입력이 됩니다.
- 스펙 변경으로 테스트가 깨지면 같은 PR에서 발견됩니다.
- 컬렉션을 수동으로 업데이트할 필요가 줄어듭니다.
- 문서, 테스트, 목 서버가 동일한 계약을 기준으로 동작합니다.
이 워크플로우에서 Apidog의 역할
Apidog의 가치는 Postman을 단순히 대체하는 데 있지 않습니다. 핵심은 OpenAPI 스펙을 팀이 사용하는 문서, 목, 테스트, 협업 워크플로우와 연결하는 것입니다.
Apidog의 스펙 우선 모드는 Git 리포지토리의 OpenAPI 스펙을 Apidog 워크스페이스로 동기화할 수 있게 합니다. 동기화된 스펙을 기준으로 다음을 사용할 수 있습니다.
- 자동 생성된 목
- 대화형 API 문서
- 테스트 시나리오
- 협업 워크스페이스
- Git 변경 사항 기반 업데이트
즉, 별도의 컬렉션을 스펙과 함께 계속 유지할 필요가 없습니다. 스펙이 Apidog가 표시하고 실행하는 모든 것의 기준이 됩니다.
이 방식은 여러 도구를 동시에 유지하는 팀에 특히 유용합니다.
예를 들어 다음 세 가지를 따로 관리하고 있다면 불일치가 발생하기 쉽습니다.
- 테스트용 Postman 컬렉션
- 스펙 렌더링용 문서 도구
- 프론트엔드 개발용 목 서버
스펙을 단일 소스로 두면 한 곳에서 변경하고, 문서·목·테스트를 동일한 계약에서 갱신할 수 있습니다.
마이그레이션을 시작하려면 기존 Postman 컬렉션을 Apidog로 변환한 뒤, 이후 변경부터 OpenAPI 스펙을 정식 문서로 관리하는 방식이 현실적입니다.
Git 워크플로우에서 스펙을 코드로 취급하기
API 스펙을 코드로 취급하는 접근 방식은 OpenAPI 문서를 애플리케이션 코드와 동일하게 관리한다는 뜻입니다.
즉, 다음을 적용합니다.
- Pull Request
- 코드 리뷰
- CI 린트
- 버전 태그
- 브랜치 전략
- 릴리스 프로세스
실행 방법은 간단합니다.
1. 스펙을 서비스 리포지토리에 저장하기
스펙을 별도의 docs 리포지토리에 두면 코드 변경과 분리되기 쉽습니다. 가능하면 API를 구현하는 서비스와 같은 리포지토리에 저장하세요.
예시:
my-service/
├── src/
├── openapi/
│ └── service.yaml
├── package.json
└── .github/
└── workflows/
└── api-tests.yml
이렇게 하면 API 구현 변경과 스펙 변경을 같은 PR에서 리뷰할 수 있습니다.
2. CI에 OpenAPI 린트 추가하기
Spectral을 사용하면 OpenAPI 스펙과 팀 규칙을 검증할 수 있습니다.
npm install -g @stoplight/spectral-cli
spectral lint openapi/service.yaml
예를 들어 다음 문제를 CI 실패로 만들 수 있습니다.
- 깨진
$ref - 누락된
description - 일관성 없는 operationId
- 정의되지 않은 응답 스키마
- 잘못된 상태 코드 사용
3. 브레이킹 변경은 브랜치로 격리하기
브레이킹 변경이 포함된 스펙은 바로 main에 병합하지 않는 것이 좋습니다.
예시:
main
├── feature/add-new-filter
└── breaking/change-user-response-schema
브레이킹 변경 브랜치에서는 API 소비자와 함께 영향 범위를 검토하고, 필요한 클라이언트 변경을 준비한 뒤 병합합니다. Apidog 워크스페이스의 브랜칭 기능을 사용하면 안정적인 스펙과 변경 중인 스펙을 분리해 작업할 수 있습니다.
4. 다운스트림 소비자는 스펙 버전을 고정하기
서비스 B가 서비스 A의 계약 테스트에 의존한다면, main의 최신 HEAD를 바로 참조하지 않는 것이 좋습니다. 대신 버전 태그를 참조하세요.
service-a-openapi@v1.4.2
이렇게 하면 서비스 A의 변경이 서비스 B의 테스트를 예고 없이 깨뜨리는 일을 줄일 수 있습니다.
새 프로젝트에서 Git 기반 API 워크플로우를 구성하려면 Git 기반 API 워크플로우 가이드를 참고할 수 있습니다.
FAQ
Postman을 완전히 사용 중단해야 하나요?
아니요. 핵심은 도구 교체가 아니라 종속성 방향 변경입니다.
Postman은 계속 사용할 수 있습니다. 특히 다음 작업에는 여전히 유용합니다.
- 탐색적 테스트
- 수동 요청 실행
- 스크립팅
- 환경 변수 기반 테스트
- 디버깅
차이점은 컬렉션을 별도로 유지 관리하지 않는다는 점입니다. 컬렉션은 테스트 실행 전 OpenAPI 스펙에서 생성합니다.
기존 Postman 스크립트와 환경 변수는 어떻게 되나요?
사전 요청 스크립트, 테스트 스크립트, 환경 변수는 별도 파일로 유지하는 것이 좋습니다.
예시:
config/
├── env-staging.json
├── env-production.json
└── test-scripts/
스펙에서 생성되는 컬렉션은 요청 구조를 담당하고, 환경 변수와 실행 로직은 별도로 관리합니다. 이렇게 하면 스펙 변경으로 컬렉션을 재생성해도 환경 설정이 덮어쓰이지 않습니다.
스펙에 아직 없는 엔드포인트는 어떻게 처리하나요?
스펙 우선 워크플로우에서는 스펙에 없는 엔드포인트를 테스트 준비가 된 API로 보지 않습니다.
실무에서는 다음 순서가 좋습니다.
- 새 엔드포인트를 구현하는 PR을 생성합니다.
- 같은 PR에 OpenAPI 경로를 추가합니다.
- CI에서 스펙 린트와 테스트 생성을 실행합니다.
- 생성된 컬렉션 또는 목을 기준으로 테스트합니다.
- 리뷰 후 병합합니다.
탐색적 개발 중이라면 로컬 스텁이나 임시 목을 사용할 수 있습니다. 이후 PR에 정식 스펙 항목을 추가하면 됩니다. 스펙 편집과 검증을 빠르게 하려면 최고의 OpenAPI 유효성 검사 도구 가이드를 참고하세요.
Apidog 스펙 우선 모드를 지금 사용할 수 있나요?
Apidog 스펙 우선 모드는 현재 베타 중입니다. Apidog를 통해 Git 동기화 워크플로우, 브랜치 지원, 자동 생성된 목이 팀의 요구 사항에 맞는지 평가할 수 있습니다.
프로덕션 워크플로우에 적용하기 전에는 다음을 확인하는 것이 좋습니다.
- 현재 OpenAPI 스펙 구조와 호환되는지
- Git 동기화 방식이 팀 브랜치 전략과 맞는지
- 목 서버와 문서 생성 결과가 기대와 일치하는지
- 접근 권한과 SSO 요구 사항을 충족하는지
이것과 내 스펙을 Postman으로 가져오는 것의 차이점은 무엇인가요?
Postman으로 OpenAPI 스펙을 가져오면 컬렉션이 생성됩니다. 하지만 보통은 일회성 변환입니다.
이후 컬렉션을 직접 수정하기 시작하면 다시 스펙과 불일치합니다.
스펙 우선 워크플로우는 다릅니다.
- 매 CI 실행마다 스펙에서 컬렉션을 재생성합니다.
- 컬렉션은 항상 최신 스펙을 기준으로 합니다.
- 컬렉션 변경이 아니라 스펙 변경을 리뷰합니다.
- 문서, 목, 테스트가 같은 입력을 사용합니다.
즉, 컬렉션이 스펙과 한 빌드 이상 어긋나지 않도록 만드는 방식입니다.
결론
Postman 컬렉션과 OpenAPI 스펙의 불일치는 Postman의 버그가 아닙니다. 명확한 종속성 없이 두 개의 API 설명을 동시에 관리할 때 발생하는 자연스러운 결과입니다.
해결책은 Git의 OpenAPI 스펙을 권위 있는 소스로 두고, Postman 컬렉션을 그 스펙에서 생성되는 다운스트림 아티팩트로 취급하는 것입니다.
이렇게 바꾸면 다음 효과를 얻을 수 있습니다.
- 스펙 변경과 테스트 실패가 같은 PR에서 발견됩니다.
- 문서, 목, 테스트가 같은 계약을 기준으로 동작합니다.
- 컬렉션을 수동으로 동기화하는 유지 관리 비용이 줄어듭니다.
- API 변경이 Git 리뷰와 CI 검증을 통과해야 하므로 품질 관리가 쉬워집니다.
Apidog를 다운로드하여 기존 OpenAPI 스펙으로 스펙 우선 모드 워크스페이스를 열어보세요. 컬렉션에서 시작하는 팀이라면 기존 Postman 컬렉션을 가져온 뒤, 이후 변경부터 OpenAPI 스펙을 정식 계약으로 관리하는 방식으로 전환할 수 있습니다.
Top comments (0)