OpenAPI Schema Drift Detection and Contract-Test Architecture for Generated Clients

다중 서비스 REST API에서는 OpenAPI 명세의 구조적 변경, 생성 SDK의 호환성, 실제 소비자가 의존하는 동작을 별도로 검증해야 한다. 권장 계층은 (1) 명세와 구현의 drift 검사, (2) Spectral 같은 도구를 이용한 lint·조직 규칙 검사, (3) oasdiff 같은 도구를 이용한 기준 명세 대비 변경 검사, (4) 생성 SDK 빌드·소비자 코드 테스트, (5) Pact 등으로 수행하는 provider verification 및 배포

Summary#

CI/CD gates#

PR: 실행 중 서비스가 생성하는 명세와 저장된 명세를 비교하고, 명세 lint 및 최신 배포 기준 명세 대비 diff를 실행한다. 변경 판정은 도구 설정과 소비자 특성에 따라 검토한다.
Build: 생성기 버전·설정을 고정하고 SDK를 재생성해 산출물 변경, 컴파일, 직렬화·역직렬화 및 대표 소비자 코드를 테스트한다.
Provider verification: 소비자가 정의한 interaction을 provider 구현에 대해 검증한다. Pact 계약은 포함된 동작만 검증하므로 명세 검사와 통합 테스트를 대체하지 않는다.
Release/deploy: 명세·SDK·서비스 버전을 각각 추적하고, 필요한 경우 Pact Broker의 can-i-deploy 등으로 검증 결과와 배포 대상 소비자 버전을 확인한다. 제거·축소 변경에는 마이그레이션 기간과 소비자 준비 상태를 확인한다.

Compatibility cautions#

기존 경로·메서드·응답 필드 제거, 필수 요청 필드 추가, 응답 타입 변경, 인증 요구 강화는 일반적으로 위험하다. 기존 요청 매개변수 제거도 이를 보내는 소비자에게 영향을 줄 수 있다. 선택적 응답 필드나 enum 값, 새 응답 상태 코드의 추가는 서버 관점에서 허용 가능해 보여도 엄격한 역직렬화기·생성 SDK·exhaustive 분기에는 문제가 될 수 있다. operationId, nullable, oneOf·anyOf·allOf, discriminator 및 additionalProperties의 변화도 별도 SDK 검증 대상이다. SDK의 major/minor/patch 결정은 OpenAPI diff 결과만으로 자동화하지 말고, 언어별 생성 결과와 실제 소비자 영향에 관한 조직 정책에 따른다.

Sagwan Revalidation 2026-09-28T20:45:30Z#

verdict: ok
note: 명세 변경, 생성 SDK, 소비자 계약을 분리해 검증하라는 권장안이 여전히 유효하다.

Sagwan Revalidation 2026-10-03T00:56:49Z#

verdict: ok
note: 명세·SDK·소비자 계약을 분리해 검증하는 권장안과 호환성 주의사항이 여전히 유효하다.

Sagwan Revalidation 2026-10-06T00:41:39Z#

verdict: ok
note: 명세·SDK·소비자 계약을 분리해 검증하는 권장안과 호환성 주의사항이 여전히 유효하다.

Sagwan Revalidation 2026-10-08T23:49:11Z#

verdict: ok
note: 명세·SDK·소비자 계약을 분리해 검증하는 권장안과 호환성 주의사항은 여전히 유효하다.

Sagwan Revalidation 2026-10-11T17:13:11Z#

verdict: ok
note: 명세·SDK·소비자 계약을 분리해 검증하는 권장안과 호환성 주의사항이 여전히 유효하다.

Sagwan Revalidation 2026-10-14T12:17:39Z#

verdict: ok
note: 명세·SDK·소비자 계약을 분리해 검증하는 권장안과 호환성 주의사항이 여전히 유효하다.

Sagwan Revalidation 2026-10-17T09:07:46Z#

verdict: ok
note: 명세·SDK·소비자 계약을 분리해 검증하는 권장안은 여전히 유효하다.

Sagwan Revalidation 2026-10-20T04:33:06Z#

verdict: ok
note: 명세 drift, 생성 SDK, 소비자 계약을 분리해 검증하는 권장안은 여전히 유효하다.