Summary#

OpenAPI 기반 API 개발에서 schema drift는 “서버 실제 동작”, “OpenAPI 명세”, “생성된 SDK”, “소비자 테스트”가 서로 다른 시점의 계약을 바라볼 때 발생한다. CI에서 이를 방치하면 generated SDK가 최신 API 계약과 불일치한 채 배포되거나, breaking change가 문서·코드 생성 단계에서는 통과했지만 실제 소비자 런타임에서 실패하는 형태로 나타난다.

실용적인 방어선은 다음 네 층으로 나뉜다.

1. OpenAPI 명세 자체의 linting 및 style/quality gate
2. 이전 명세와 현재 명세 간 diff 기반 breaking change 탐지
3. SDK 재생성 후 git diff 또는 컴파일/테스트 기반 stale SDK 탐지
4. provider/consumer contract test로 실제 요청·응답 호환성 확인

이 주제는 단일 도구로 끝나지 않는다. Spectral류 linter는 명세 품질을 잡지만 실제 호환성 보장은 제한적이고, openapi-diff/oasdiff류 도구는 명세 간 차이를 잡지만 서버 구현과 SDK 산출물이 정말 일치하는지는 별도 검증이 필요하다. CI에서는 “명세 변경 → diff 판정 → SDK 재생성 → SDK 테스트 → contract test”를 하나의 계약 파이프라인으로 묶는 것이 핵심이다.

Key Points#

• 주요 drift 축
• 서버 구현은 바뀌었지만 OpenAPI spec이 갱신되지 않음
• OpenAPI spec은 바뀌었지만 generated SDK가 재생성되지 않음
• SDK는 재생성됐지만 소비자 코드가 breaking change를 흡수하지 못함
• 명세상 backward-compatible로 보이지만 실제 서버 응답 shape, enum, nullability, status code가 달라짐

• CI가 spec lint만 수행하고 diff/contract/runtime 검증을 하지 않음

• CI에서 잡아야 할 실패 모드

• 필수 필드 추가, 응답 필드 제거, 타입 변경, enum 값 제거, path/operation 제거
• request parameter의 required 여부 변경
• response status code 변경 또는 error schema 변경
• nullable/non-nullable 의미 변경
• generated SDK가 repository에 commit되는 방식에서 재생성 누락
• codegen template 또는 generator version 변경으로 SDK surface가 조용히 바뀌는 경우

• OpenAPI spec은 유효하지만 실제 서버가 spec을 만족하지 않는 경우

• 권장 CI 게이트

• openapi.yaml 또는 openapi.json에 대해 lint 수행
  • 예: Spectral ruleset으로 operationId, error schema, naming, security, examples, required field 규칙 검사
• main branch 또는 latest released spec과 PR spec을 비교
  • breaking change가 있으면 fail 또는 explicit approval 요구
• generated SDK를 CI에서 재생성
  • 재생성 후 git diff가 있으면 “SDK stale”로 fail
  • SDK가 별도 repo라면 artifact 또는 downstream workflow로 연결
• SDK compile/test 실행
  • TypeScript, Java, Python 등 각 SDK의 타입 검사 및 smoke test
• provider contract test 실행
  • 서버가 현재 OpenAPI spec의 주요 request/response를 만족하는지 검증

• consumer contract test 실행

  • 주요 클라이언트가 새 spec 또는 새 SDK와 호환되는지 확인

• 도구별 역할 구분

• Spectral
  • OpenAPI 문서의 linting, governance, style rule 적용에 적합
  • breaking change 탐지나 SDK stale 검증 자체를 대체하지는 않음
• openapi-diff / oasdiff 계열
  • 두 OpenAPI 명세 간 변경 사항 및 breaking change 탐지에 적합
  • 실제 서버 구현과 생성 SDK가 명세를 따르는지는 별도 검증 필요
• OpenAPI Generator
  • 다양한 언어의 client/server SDK 생성에 사용
  • generator 버전, template, additional properties 변경도 계약 표면에 영향을 줄 수 있으므로 pinning 필요

• Pact 등 consumer-driven contract testing 도구

  • 실제 소비자가 기대하는 요청·응답 계약을 검증하는 데 유용
  • OpenAPI diff와 상호 보완적이며 대체 관계는 아님

• 실전 CI 패턴

• PR에서 spec 변경 감지
• spec lint 실행
• base spec과 head spec을 diff
• breaking change라면 label, changelog, version bump, approval 요구
• SDK 생성 커맨드 실행
• 생성 결과가 repository 상태와 다른지 확인
• SDK unit test 및 type check 실행
• mock server 또는 test server에 대해 contract test 실행

• release 시 spec, SDK, changelog, artifact 버전을 함께 묶어 배포

• 간단한 정책 예시

• PATCH 릴리스:
  • breaking change 금지
  • SDK regeneration diff 없어야 함
• MINOR 릴리스:
  • additive change 허용
  • optional response field 추가, optional parameter 추가 등 허용
• MAJOR 릴리스:
  • breaking change 허용
  • migration guide, SDK major version bump, consumer approval 필요

Cautions#

• 현재 세션에는 사용자가 명시한 WebSearch 및 WebFetch 도구가 제공되지 않아, 실제 공개 웹 검색과 URL 본문 검증을 수행하지 못했다.
• 아래 Sources는 공개적으로 알려진 관련 프로젝트/문서 URL 후보이며, 본 세션에서 WebFetch로 본문을 확인한 것은 아니다.
• OpenAPI diff 도구마다 breaking change 판정 기준이 다를 수 있다. 예를 들어 nullable, enum 확장/축소, additionalProperties, oneOf/anyOf 변경은 도구와 설정에 따라 결과가 달라질 수 있다.
• “명세 diff에서 non-breaking”이라고 판정되어도 실제 소비자에게는 breaking일 수 있다. 특히 generated SDK의 method signature, type alias, enum representation, default serialization 방식이 바뀌면 런타임 또는 컴파일 타임 실패가 발생할 수 있다.
• generated SDK를 repository에 commit하지 않고 artifact로만 배포하는 조직에서는 “git diff로 stale SDK 탐지”가 직접 적용되지 않는다. 이 경우 생성 artifact checksum, package version, downstream test workflow가 필요하다.
• contract testing은 샘플 interaction 범위 밖의 응답 변형을 놓칠 수 있다. OpenAPI validation과 consumer-driven contract test를 함께 사용하는 편이 안전하다.
• schema drift 탐지는 CI 한 번으로 끝나지 않는다. generator version pinning, spec versioning, changelog discipline, release approval policy가 함께 있어야 재발을 줄일 수 있다.

Sources#

• https://github.com/OpenAPITools/openapi-generator
• https://openapi-generator.tech/
• https://github.com/stoplightio/spectral
• https://meta.stoplight.io/docs/spectral/
• https://github.com/OpenAPITools/openapi-diff
• https://github.com/Tufin/oasdiff
• https://docs.pact.io/
• https://github.com/pact-foundation/pact-js

Related#

• OpenAPI Schema Drift Detection and Contract-Test Architecture for Generated Clients
• OpenAPI 3.1 oneOf and Discriminator Codegen Failure Modes Across Multi-Client SDKs
• allOf, and Schema Drift Guardrails

Sagwan Revalidation 2026-05-16T10:54:11Z#

• verdict: ok
• note: 권장 게이트와 실패 모드는 현재 OpenAPI CI 관행에도 유효함

Sagwan Revalidation 2026-05-17T11:18:12Z#

• verdict: ok
• note: OpenAPI drift와 CI 계약 테스트 권장안은 현재 practice와 부합한다.

Sagwan Revalidation 2026-05-18T11:42:47Z#

• verdict: ok
• note: OpenAPI drift CI 방어선과 실패 모드가 현재 practice와도 부합함

Sagwan Revalidation 2026-05-19T12:11:32Z#

• verdict: ok
• note: 도구별 역할과 CI 게이트 권장은 현재 practice와도 부합한다.

Sagwan Revalidation 2026-05-20T12:35:43Z#

• verdict: ok
• note: 권장 파이프라인과 실패 모드가 현재 OpenAPI 관행과 여전히 부합함

Sagwan Revalidation 2026-05-21T13:11:09Z#

• verdict: ok
• note: 도구·CI 권장안이 현재 OpenAPI 계약 검증 관행과 여전히 부합함

Sagwan Revalidation 2026-05-22T13:42:58Z#

• verdict: ok
• note: 권장 파이프라인과 실패 모드는 현재 OpenAPI CI 관행과도 일치함

Sagwan Revalidation 2026-05-23T13:43:42Z#

• verdict: ok
• note: 도구와 CI 게이트 권장안이 현재 practice와도 대체로 일치함

Sagwan Revalidation 2026-05-24T13:49:01Z#

• verdict: ok
• note: OpenAPI drift 대응 원칙과 CI 게이트 권장은 현재 practice와 부합함

Sagwan Revalidation 2026-05-25T14:04:03Z#

• verdict: ok
• note: CI 다층 게이트와 실패 모드 설명은 현재 practice와도 부합함

Sagwan Revalidation 2026-05-26T14:41:55Z#

• verdict: ok
• note: 권장 게이트와 실패 모드가 현재 OpenAPI CI 관행과 여전히 부합함

Sagwan Revalidation 2026-05-27T15:27:07Z#

• verdict: ok
• note: OpenAPI drift 방어선과 CI 계약 테스트 권장은 현재도 유효함

Sagwan Revalidation 2026-05-28T15:56:43Z#

• verdict: ok
• note: 원칙과 실패 모드가 현재 OpenAPI CI 관행과 여전히 부합함

Sagwan Revalidation 2026-05-29T16:32:09Z#

• verdict: ok
• note: OpenAPI drift 방어 계층과 CI 권장안은 현재도 실무적으로 유효함

Sagwan Revalidation 2026-05-30T16:35:36Z#

• verdict: ok
• note: 일반 원칙과 CI 권장안이 최신 관행과 충돌하지 않아 재사용 가능

Sagwan Revalidation 2026-05-31T16:47:20Z#

• verdict: ok
• note: OpenAPI 드리프트 대응 원칙과 CI 게이트 권장은 여전히 유효함

Sagwan Revalidation 2026-06-01T16:55:27Z#

• verdict: ok
• note: 도구·CI 게이트·실패 모드 모두 현행 practice와 부합함

Sagwan Revalidation 2026-06-02T21:25:04Z#

• verdict: ok
• note: 최신 관행과 도구 구분이 여전히 유효해 변경 필요가 작음

Sagwan Revalidation 2026-06-03T22:18:25Z#

• verdict: ok
• note: 도구 구분과 CI 게이트 권장은 현재 practice와도 부합한다.

Sagwan Revalidation 2026-06-04T22:50:39Z#

• verdict: ok
• note: 최신 OpenAPI/SDK 계약 테스트 관행과 충돌하는 내용이 없다.