우리 팀은 2년 동안 두 가지를 모두 유지했습니다. 결국 두 가지는 서로 어긋나기 시작했고, 그 어긋남에 대한 사후 분석(postmortem)이 바로 이 글을 쓰게 된 이유입니다.

처음에는 두 가지를 모두 유지하는 것이 매우 합리적으로 보였습니다.

우리의 OpenAPI specification은 API를 문서화했습니다.

우리의 Postman collection은 개발자들이 API를 탐색하고 테스트하는 것을 도왔습니다.

각각은 서로 다른 목적을 수행했습니다.

적어도 우리는 그렇게 생각했습니다.

API가 성장함에 따라, 미묘한 변화가 일어났습니다.

애플리케이션에 새로운 엔드포인트(endpoint)가 추가됩니다.

OpenAPI specification은 코드 리뷰 과정에서 업데이트됩니다.

Postman collection은 일주일 뒤에 업데이트됩니다.

때로는 말이죠.

어떤 때는 업데이트되지 않기도 했습니다.

몇 달 후, 개발자들은 다음과 같은 질문을 하기 시작했습니다:

• "어떤 요청 본문(request body)이 정확한가요?"
• "왜 문서는 이렇게 말하는데 Postman은 다른 것을 보내나요?"
• "왜 생성된 SDK는 컬렉션에 없는 필드를 허용하나요?"

결국 우리는 더 이상 하나의 진실의 원천(source of truth)을 가지고 있지 않다는 것을 깨달았습니다.

우리는 두 개를 가지고 있었습니다.

그리고 그 어느 것도 운영 환경(production)과 완전히 일치하지 않았습니다.

그 경험은 우리로 하여금 각 형식의 역할을 재고하게 만들었습니다.

결론은 어느 하나가 "더 낫다"는 것이 아니었습니다.

그것들은 서로 다른 문제를 해결하며, 권위 있는 API 계약(API contract)으로서 잘 확장되는 것은 오직 하나뿐이라는 것이었습니다.

각 형식이 실제로 모델링하는 것 (그리고 모델링하지 못하는 것)

많은 팀이 저지르는 첫 번째 실수는 Postman collections와 OpenAPI specifications가 동일한 것을 나타낸다고 가정하는 것입니다.

그렇지 않습니다.

그들의 목표는 근본적으로 다릅니다.

Postman Collection이 모델링하는 것

Postman collection은 상호작용(interactions)을 기술합니다.

다음 내용을 포함합니다:

• 요청 (Requests)
• 헤더 (Headers)
• 변수 (Variables)
• 인증 (Authentication)
• 예시 페이로드 (Example payloads)
• 테스트 스크립트 (Test scripts)
• 사전 요청 스크립트 (Pre-request scripts)
• 환경 값 (Environment values)

그 초점은 실행(execution)에 있습니다.

개발자는 즉시 요청을 보내고 응답을 관찰할 수 있습니다.

이는 개발 및 디버깅(debugging) 과정에서 믿을 수 없을 정도로 가치 있는 일입니다.

모델링을 잘 하지 못하는 것

컬렉션은 자연스럽게 다음을 기술하지 못합니다:

• 완전한 API 계약 (API contracts)
• 재사용 가능한 스키마 (Reusable schemas)
• 타입 관계 (Type relationships)
• 다형성 (Polymorphism)
• 코드 생성 메타데이터 (Code generation metadata)
• 검증 규칙 (Validation rules)

Postman이 시간이 흐르면서 스키마 관련 기능을 추가해 왔지만, 계약 모델링 (contract modeling)은 Postman의 주요 설계 목표가 아닙니다.

OpenAPI Specification이 모델링하는 것

OpenAPI는 API 자체를 기술하는 데 집중합니다.

다음 항목들을 정의합니다:

• 엔드포인트 (Endpoints)
• 작업 (Operations)
• 파라미터 (Parameters)
• 요청 본문 (Request bodies)
• 응답 스키마 (Response schemas)
• 인증 (Authentication)
• 데이터 모델 (Data models)
• 에러 응답 (Error responses)

모든 것이 계약 (contract)을 중심으로 구조화되어 있습니다.

그 계약은 다음과 같은 기능을 수행할 수 있습니다:

• 문서화 (Documentation)
• 클라이언트 SDK 생성 (Client SDK generation)
• 모크 서버 (Mock servers)
• 계약 검증 (Contract validation)
• 테스트 생성 (Test generation)

OpenAPI는 기본적으로 실행 형식 (execution format)이 아닙니다.

그것은 명세 형식 (specification format)입니다.

이 차이는 매우 중요합니다.

50개 엔드포인트 지점에서의 드리프트 (Drift) 문제

규모가 작은 API의 경우, 두 형식을 모두 유지하는 것이 고통스럽게 느껴지는 경우는 드뭅니다.

엔드포인트가 10개라고 가정해 봅시다.

매 변경 사항마다 두 개의 파일을 업데이트하는 것은 관리할 만한 수준입니다.

이제 50개라고 가정해 봅시다.

그다음은 100개입니다.

결국 모든 API 변경 시마다 다음 항목들을 업데이트해야 합니다:

• 구현체 (Implementation)
• OpenAPI 명세 (OpenAPI specification)
• Postman 컬렉션 (Postman collection)

세 가지 산출물 (artifacts).

드리프트 (drift)가 발생할 세 가지 기회입니다.

드리프트가 시작되는 방식

개발자가 다음을 추가합니다:

PATCH /customers/{id}

OpenAPI 명세는 즉시 업데이트됩니다.

...

PUT /customers/{id}

당장 무엇인가가 깨지지는 않습니다.

몇 주 후:

누군가는 Postman 컬렉션을 가져옵니다 (import).

다른 누군가는 OpenAPI로부터 SDK를 생성합니다.

이제 서로 다른 팀이 서로 다른 계약을 사용하고 있습니다.

둘 다 올바르게 보입니다.

하지만 어느 것도 현실과 완벽하게 일치하지 않습니다.

시간이 지날수록 상황이 악화되는 이유

드리프트는 복리로 쌓입니다.

각각의 불일치하는 업데이트는 미래의 또 다른 불일치를 만들어냅니다.

결국 개발자들은 두 산출물 모두를 신뢰하지 않게 됩니다.

대신 그들은 구현체를 직접 조사합니다.

그것은 바로 문서화가 방지해야 하는 상황입니다.

각 도구 주변의 생태계: 코드 생성, 문서화, 모크, 그리고 테스트

OpenAPI의 가장 큰 강점 중 하나는 주변 생태계입니다.

단일 명세(Specification)만으로 다음을 생성할 수 있습니다:

• 대화형 문서화 (Interactive documentation)
• 타입 안정성이 보장된 SDK (Type-safe SDKs)
• 모크 서버 (Mock servers)
• 검증 미들웨어 (Validation middleware)
• 계약 테스트 (Contract tests)
• API 클라이언트 (API clients)

모든 것이 하나의 계약(Contract)에서 시작됩니다.

Postman 도구 (Postman Tooling)

Postman은 다른 영역에서 탁월한 성능을 발휘합니다.

예시로는 다음과 같은 것들이 있습니다:

• 수동 탐색 (Manual exploration)
• 팀 협업 (Team collaboration)
• 환경 관리 (Environment management)
• 요청 실행 (Request execution)
• 자동화된 컬렉션 (Automated collections)
• 모니터링 (Monitoring)

이는 개발자와 QA 엔지니어에게 매우 뛰어난 생산성 도구입니다.

OpenAPI가 앞서 나가는 지점

API 규모가 커질수록, 계약(Contract)의 가치는 점점 더 높아집니다.

팀은 다음과 같은 요소들에 의존하기 시작합니다:

• 코드 생성 (Code generation)
• 지속적인 검증 (Continuous validation)
• 소비자 주도 계약 (Consumer-driven contracts)
• API 거버넌스 (API governance)
• 버전 호환성 (Version compatibility)

이러한 워크플로우는 자연스럽게 **OpenAPI 명세 (OpenAPI specification)**와 일치합니다.

두 도구는 서로를 보완합니다

이것은 '이것 아니면 저것'을 선택해야 하는 상황이 아닙니다.

Postman은 사람이 API와 상호작용하는 것을 돕습니다.

OpenAPI는 도구가 API를 이해하는 것을 돕습니다.

이것은 중요한 차이점입니다.

예시를 잃지 않고 Postman → OpenAPI로 마이그레이션하기

많은 팀이 OpenAPI 도입을 망설이는 이유 중 하나는 수년간 큐레이션해 온 요청 예시들을 잃게 될까 봐 두렵기 때문입니다.

다행히도, 대개 그럴 필요는 없습니다.

단계적인 마이그레이션은 놀라울 정도로 잘 작동합니다.

1단계: 기존 컬렉션 내보내기 (Export Existing Collections)

대부분의 컬렉션에는 이미 가치 있는 예시들이 포함되어 있습니다.

이것들이 사라져서는 안 됩니다.

먼저 그것들을 내보내세요.

2단계: 기준 명세 생성하기 (Generate a Baseline Specification)

여러 도구를 사용하여 Postman 컬렉션을 초기 OpenAPI 문서로 변환할 수 있습니다.

출력물은 대개 정리가 필요하지만, 매우 훌륭한 시작점이 됩니다.

3단계: 예시 승격시키기 (Promote Examples)

유용한 요청 및 응답 예시를 다음 항목으로 이동시키세요:

• 요청 스키마 (Request schemas)
• 응답 예시 (Response examples)
• 컴포넌트 (Components)
• 재사용 가능한 객체 (Reusable objects)

예시가 컬렉션 내부에 숨겨진 채로 남는 대신, 명세 자체의 일부가 됩니다.

4단계: 새로운 컬렉션 생성하기 (Generate New Collections)

OpenAPI가 권위(authoritative)를 갖게 되면, 명세(specification)가 변경될 때마다 Postman 컬렉션을 다시 생성(regenerate)하세요.

두 개의 소스를 수동으로 유지하는 대신, 하나만 유지하세요.

다른 하나는 생성하는 것입니다.

이 단일 워크플로우(workflow)는 대부분의 동기화 문제를 제거합니다.

두 가지를 모두 유지하는 것이 실제로 의미 있는 경우

지금까지 제가 쓴 내용에도 불구하고, 두 가지를 모두 유지하는 것이 전적으로 합리적인 상황이 한 가지 있습니다.

바로 소비자 워크플로우(Consumer workflows)입니다.

외부 개발자의 온보딩(onboarding) 경험을 상상해 보세요.

OpenAPI는 다음을 제공합니다:

• 문서화 (Documentation)
• 스키마 (Schemas)
• SDK 생성 (SDK generation)

Postman은 다음을 제공합니다:

• 즉시 실행 가능한 요청 (Ready-to-run requests)
• 인증 도우미 (Authentication helpers)
• 환경 변수 (Environment variables)
• 예시 워크플로우 (Example workflows)

이것들은 서로 다른 대상(audience)에게 서비스를 제공합니다.

컬렉션이 독립적으로 유지되는 것이 아니라 OpenAPI로부터 생성되는 한, 두 가지 모두 가치를 유지합니다.

핵심은 어떤 아티팩트(artifact)가 계약(contract)을 소유하는지 이해하는 것입니다.

실질적인 권장 사항

만약 제가 오늘 새로운 API 프로젝트를 시작한다면, 저의 워크플로우는 다음과 같을 것입니다.

1단계

OpenAPI를 사용하여 API를 설계합니다.

2단계

계약(contract)을 검토합니다.

3단계

다음 항목들을 생성합니다:

• 문서화 (Documentation)
• SDK
• 모의 서버 (Mock servers)
• 계약 테스트 (Contract tests)
• Postman 컬렉션 (Postman collections)

4단계

API를 구현합니다.

5단계

계약에 따라 구현 사항을 검증(validate)합니다.

무엇이 빠져 있는지 주목해 보세요.

수동 동기화(Manual synchronization)입니다.

모든 아티팩트는 동일한 명세(specification)에서 기원합니다.

그것이 진정한 이점입니다.

팀들이 저지르는 흔한 실수

시간이 흐르면서 저는 몇 가지 반복되는 패턴을 보았습니다.

Postman을 문서화(Documentation)로 취급하는 것

컬렉션은 요청을 설명합니다.

그것들은 포괄적인 API 계약(API contracts)이 아닙니다.

두 가지를 모두 수동으로 유지하는 것

이는 거의 항상 드리프트(drift, 괴리)로 이어집니다.

예시(Examples)를 무시하는 것

예시는 가치가 있습니다.

예시를 명세(specification) 안으로 옮기세요.

마이그레이션(migration) 중에 이를 잃어버리지 마세요.

컬렉션만을 대상으로 테스트를 작성하는 것

테스트는 단순히 요청 컬렉션만을 검증할 때보다 API 계약(API contract)을 검증할 때 더 강력해집니다.

OpenAPI 도입을 미루는 것

API가 커질수록 나중에 마이그레이션(migration)하는 것은 더 어려워집니다.

일찍 시작하는 것이 보통 이득이 됩니다.

마치며 (Final Thoughts)

Postman 대 OpenAPI에 관한 논쟁은 종종 이들이 서로 경쟁하는 기술이라고 가정합니다.

저는 그것이 이들을 바라보는 올바른 방식이라고 생각하지 않습니다.

Postman은 API와 상호작용(interacting)하는 데 탁월합니다.

OpenAPI는 API를 기술(describing)하는 데 탁월합니다.

이것들은 상호 보완적인 목표입니다.

팀들이 문제에 직면하는 지점은 두 가지 모두를 독립적인 진실의 원천(sources of truth)으로 취급할 때입니다.

그러한 접근 방식은 소규모 프로젝트에는 효과적이지만, API가 진화함에 따라 점점 더 어려워집니다.

API가 수십 개의 엔드포인트(endpoints)에 도달하면, 수동으로 유지 관리되는 여러 계약(contracts)을 동기화하는 것은 생산성 측면의 이점이라기보다 유지 관리의 문제가 됩니다.

대부분의 조직에게 지속 가능한 접근 방식은 명확합니다:

OpenAPI를 권위 있는 계약(authoritative contract)으로 사용하십시오.

그 계약으로부터 문서(documentation), SDK, 모크(mocks), 테스트, 그리고 심지어 Postman 컬렉션까지 생성하십시오.

그다음, 모든 산출물(artifact)이 진실의 원천이 되도록 요구하는 대신, 각 도구가 가장 잘하는 일을 하도록 두십시오.

워크플로우를 평가하거나 API 툴링(tooling) 구조를 어떻게 잡을지 결정하고 있다면, **Total Shift Left vs Postman 분석**을 통해 계약 우선(contract-first) 접근 방식이 컬렉션 우선(collection-first) 워크플로우와 어떻게 다른지, 그리고 현대적인 API 개발 프로세스 내에서 각각이 어디에 적합한지에 대한 실질적인 비교를 확인할 수 있습니다.