API 명세 코드로 다루기: 의미와 방법

API 계약은 아마도 세 군데에 동시에 존재할 것입니다. 위키의 다이어그램. 누군가 지난 분기에 내보낸 Postman 컬렉션. 두 릴리스 전에 실행 중인 서비스와 달라진 손으로 작성된 Markdown 문서. 이 세 가지가 일치하지 않으면 팀은 추측에 의존하게 됩니다. 추측은 통합을 망가뜨립니다.

API 스펙을 코드로 취급하면 이 문제가 해결됩니다. 하나의 OpenAPI 파일을 작성하고, Git에 커밋하며, 다른 소스 파일처럼 검토합니다. 이 단일 파일에서 모의(mocks), 테스트, 문서, 그리고 SDK를 생성합니다. 스펙은 더 이상 나중에 생각할 거리가 아니라, 모든 사람이 기반으로 하는 계약이 됩니다.

이 가이드는 스펙-애즈-코드(spec-as-code)가 무엇을 의미하는지, OpenAPI 파일이 왜 애플리케이션 코드와 동일한 엄격함을 가져야 하는지, 그리고 도구와 씨름하지 않고 워크플로를 실행하는 방법을 설명합니다.

버튼

스펙-애즈-코드(Spec-as-code)란 무엇인가

스펙-애즈-코드(Spec-as-code)는 API 정의가 버전 관리 시스템에 저장되는 일반 텍스트 파일이라는 의미입니다. 데이터베이스 레코드가 아닙니다. 공유 링크가 있는 호스팅된 문서도 아닙니다. git diff, 브랜치, 병합이 가능한 파일입니다.

이 아이디어는 문서가 설명하는 코드와 동일한 저장소에 있고 동일한 파이프라인을 통해 배포되는 docs-as-code에서 직접 빌려왔습니다. 스펙-애즈-코드는 API 계약 자체에 동일한 규율을 적용합니다. OpenAPI 문서(YAML 또는 JSON)가 아티팩트(artifact)이며, 그 외 모든 하위 구성 요소는 이 문서로부터 생성됩니다.

이러한 변화는 한 가지 큰 결과를 낳습니다. 스펙이 단일 진실 공급원(single source of truth)이 됩니다. 개발자가 /users/{id}가 무엇을 반환하는지 알고 싶을 때, 오래된 위키 페이지가 아니라 스펙을 읽습니다. QA가 테스트를 작성할 때, 스펙에 대해 어설션합니다. 파트너가 통합할 때, 스펙에서 생성된 SDK를 가져옵니다. 하나의 파일, 여러 출력물입니다.

스펙을 코드처럼 다뤄야 하는 이유

스펙이 일단 Git에 파일로 존재하면, 소스 코드에 대해 이미 신뢰하는 모든 워크플로를 상속받게 됩니다.

풀 리퀘스트(pull requests)에서 검토. 엔드포인트 변경 사항은 PR에서 차이점(diff)으로 나타납니다. 검토자들은 어떤 필드가 변경되었는지, 어떤 상태 코드가 추가되었는지, 응답 형태가 하위 호환성을 손상시켰는지 정확히 알 수 있습니다. 호환성을 깨는 변경(breaking change)은 더 이상 프로덕션에서의 놀라움이 아닙니다. 병합 전의 댓글 스레드가 됩니다. 이것이 Git-네이티브 API 워크플로의 핵심입니다.

차이점(diff) 친화적인 형식. 일반 YAML은 깨끗하게 차이점을 보여줍니다. 5줄의 변경 사항을 몇 초 만에 읽고 이해할 수 있습니다. "무엇이 변경되었는지" 알 수 없는 바이너리 내보내기나 호스팅된 도구와 비교해 보세요. 스펙이 Git에 있으면, blame, 기록, 그리고 차이점 모두 그냥 작동합니다.

진정한 버전 관리. 모든 변경 사항에는 커밋, 작성자 및 타임스탬프가 있습니다. 릴리스에 태그를 지정하고, v2 재설계를 위해 브랜치를 만들고, 한 명령으로 잘못된 변경 사항을 롤백할 수 있습니다. API 기록은 감사 가능하게 됩니다. 태그 지정 및 브랜치 전략에 대한 자세한 내용은 Git을 이용한 OpenAPI 버전 관리를 참조하세요.

단일 진실 공급원. 모의(mocks), 테스트, 문서가 모두 동일한 파일에서 파생되기 때문에 독립적으로 벗어날 수 없습니다. 스펙을 업데이트하고, 다시 생성하면 모든 출력이 일관성을 유지합니다.

실제 두 가지 접근 방식을 비교한 표입니다.

고려 사항	호스팅된 도구의 스펙	코드로 된 API 스펙
변경 검토	수동, 놓치기 쉬움	PR 차이점, 검토 차단
기록	제한적이거나 특정 벤더에 종속됨	전체 Git 로그
롤백	대부분 수동	`git revert`
진실 공급원	모호함	커밋된 파일
CI 통합	추가 설치(Bolt-on)	네이티브

아티팩트로서의 OpenAPI

OpenAPI는 널리 지원되고 기계가 읽을 수 있기 때문에 스펙에 대한 명확한 형식입니다. 저장소에 보관할 수 있는 OpenAPI 3.1 파일의 작지만 완전한 조각입니다.

openapi: 3.1.0
info:
 title: Orders API
 version: 1.2.0
paths:
 /orders/{orderId}:
 get:
 summary: Get an order by ID
 operationId: getOrder
 parameters:
 - name: orderId
 in: path
 required: true
 schema:
 type: string
 format: uuid
 responses:
 "200":
 description: The requested order
 content:
 application/json:
 schema:
 $ref: "#/components/schemas/Order"
 "404":
 description: Order not found
components:
 schemas:
 Order:
 type: object
 required: [id, status, total]
 properties:
 id:
 type: string
 format: uuid
 status:
 type: string
 enum: [pending, shipped, delivered]
 total:
 type: number
 format: float

이 파일이 계약입니다. Order에 필드를 추가하면 차이점(diff)이 한 줄로 표시됩니다. status 열거형을 변경하면 검토자가 즉시 확인할 수 있습니다. 서비스 코드 옆의 api/openapi.yaml 아래에 두면, 스펙은 설명하는 구현과 함께 이동합니다.

스펙과 문서

하나의 소스 파일이 주는 이점은 그 파일로부터 생성하는 모든 것입니다.

모의(Mocks). 모의 서버를 스펙에 연결하면 단일 엔드포인트가 구축되기도 전에 실행 가능한 API를 얻을 수 있습니다. 프론트엔드 및 모바일 팀은 첫날부터 계약에 따라 통합을 시작합니다. 스펙이 변경되면 모의도 함께 변경됩니다.

테스트. 라이브 서비스가 스펙과 일치하는지 확인하는 계약 테스트를 생성합니다. 배포된 엔드포인트가 스펙에 선언되지 않은 필드를 반환하면 테스트가 실패합니다. 이는 고객이 발견하기 전에 계약과 실행 중인 코드 간의 불일치를 잡아냅니다.

문서. 스펙을 자동으로 참조 문서로 렌더링합니다. 더 이상 아무도 엔드포인트 테이블을 손으로 작성하지 않습니다. 문서가 스펙과 일치하는 이유는 문서가 렌더링된 스펙이기 때문입니다.

SDK. 동일한 파일에서 여러 언어로 클라이언트 라이브러리를 생성합니다. 파트너는 항상 현재 계약을 반영하는 타입이 지정된 SDK를 받습니다.

각 출력은 스펙의 함수입니다. 입력을 변경하고 출력을 다시 생성하면 일관성이 자동으로 유지됩니다.

Apidog가 스펙을 진실 공급원으로 만드는 방법

스펙-애즈-코드를 수동으로 실행하는 것은 CLI, 모의 서버, 문서 생성기 및 Git 훅을 함께 연결하는 것을 의미합니다. Apidog는 이를 하나의 워크플로로 통합합니다.

Apidog의 Spec-First 모드는 OpenAPI 파일을 신뢰할 수 있는 정의로 취급합니다. 스펙에 따라 엔드포인트를 설계하면 Apidog는 모의(mocks), 테스트 및 문서를 스펙과 완벽하게 동기화합니다.

이를 실용적으로 만드는 부분은 양방향 Git 동기화입니다. Apidog는 저장소에서 OpenAPI 파일을 읽고 변경 사항을 다시 저장소에 쓸 수 있으므로, Git의 파일과 Apidog의 프로젝트가 일치하게 유지됩니다. 시각적 디자인이 빠를 때는 그렇게 하고, YAML을 직접 편집하는 것이 빠를 때는 그렇게 하며, 두 경로 모두 동일하게 커밋된 파일로 이어집니다. 이는 PR 검토 흐름을 그대로 유지하면서 팀에 더 풍부한 편집기를 제공합니다. 스펙 변경 사항을 업스트림에 푸시하는 방법에 대한 자세한 내용은 GitHub에 OpenAPI 스펙을 동기화하는 방법을 참조하세요.

결과적으로: OpenAPI 파일은 단일 진실 공급원으로 유지되고, 시각적 도구는 파일을 대체하는 대신 그 위에 위치합니다.

흔히 겪는 문제점

스펙-애즈-코드는 간단하지만, 몇 가지 함정이 팀을 일찍이 붙잡습니다.

스펙과 구현 간의 불일치. 스펙을 작성하는 것만으로는 충분하지 않습니다. 실행 중인 서비스가 스펙과 일치하는지 확인하는 아무것도 없다면, 둘은 조용히 멀어집니다. CI에 계약 테스트를 추가하여 불일치가 발생하면 고객이 아닌 빌드가 실패하도록 하세요.

생성된 스펙 대 수동 작성된 스펙 혼동. 스펙이 코드 주석에서 생성된 것인지 아니면 소스로 수동으로 작성된 것인지 결정하세요. 둘을 섞으면 어느 부분이 권한이 있는지 아무도 모르는 파일이 됩니다. 한 방향을 선택하세요. 스펙이 진실 공급원이라면, 코드 주석을 두 번째 마스터 복사본이 아닌 스펙에 대해 확인하는 대상으로 취급하세요.

스펙을 계약이 아닌 문서로 취급하는 것. 단순히 읽기만 하는 스펙은 문서입니다. 모의(mocks), 테스트, SDK를 생성하는 스펙은 계약입니다. 가치는 파일이 존재한다는 것에서 오는 것이 아니라 출력을 연결하는 것에서 나옵니다.

검토 건너뛰기. 검토 없이 병합된 Git의 스펙은 단지 Git의 파일일 뿐입니다. 중요한 것은 풀 리퀘스트(pull request)입니다. 코드에 대해 하는 것과 동일하게 스펙 변경 사항에 대한 검토를 요구하세요.

시작하기

스펙-애즈-코드를 점진적으로 도입할 수 있습니다.

스펙을 커밋하세요. OpenAPI 파일을 api/openapi.yaml과 같은 알려진 경로의 저장소로 옮기세요.
PR 검토를 의무화하세요. 스펙 변경 사항이 코드와 동일한 검토 절차를 거치도록 하세요. 차이점(diffs)이 대화의 중심이 됩니다.
하나의 출력을 생성하세요. 모의(mocks) 또는 문서부터 시작하세요. 스펙을 생성기에 연결하여 파일이 업데이트될 때 출력이 함께 업데이트되도록 하세요.
CI 검사를 추가하세요. 모든 PR에서 스펙을 린트하세요. 병합 전에 유효하지 않은 OpenAPI를 잡아내세요.
계약 테스트로 루프를 닫으세요. 모의(mocks)와 문서가 제대로 작동하기 시작하면, 라이브 서비스가 스펙과 일치하는지 확인하는 테스트를 추가하세요.

각 단계는 독립적으로 가치를 제공합니다. 첫 번째 단계에서 가치를 얻고, 각 추가 사항으로 그 가치를 더합니다.

이 변화는 설명하기에는 작지만 효과는 큽니다. Git에 있는 하나의 파일이 코드처럼 검토되고, 모든 하위 구성 요소를 생성합니다. 시각적 편집과 Git 동기화 기능이 내장되어 있기를 원한다면, Apidog의 Spec-First 모드를 사용해 보세요. 그리고 OpenAPI 파일이 단일 진실 공급원으로 유지되도록 하세요.

자주 묻는 질문

“API 스펙-애즈-코드”는 “문서-애즈-코드”와 동일한가요?

둘은 동일한 철학을 공유합니다: 아티팩트(artifact)를 버전 관리 시스템에 보관하고 일반 파이프라인을 통해 배포하는 것입니다. 문서-애즈-코드(Docs-as-code)는 이를 문서에 적용하고, 스펙-애즈-코드(Spec-as-code)는 API 계약 자체에 적용합니다. 실제로는 서로 강화되는 관계입니다. 커밋된 스펙에서 생성된 문서는 정의상 문서-애즈-코드이기 때문입니다.

스펙 파일은 어떤 형식을 사용해야 하나요?

YAML 형식의 OpenAPI가 일반적인 선택입니다. YAML은 풀 리퀘스트에서 깨끗하게 차이점(diff)을 보여주고 사람이 읽기 쉬우며, 동시에 모의(mocks), 테스트, SDK 생성을 위해 기계가 파싱할 수 있습니다. JSON도 작동하지만, YAML이 더 깔끔한 차이점을 생성하는 경향이 있습니다.

스펙이 실제 API와 멀어지는 것을 어떻게 막을 수 있나요?

CI에 계약 테스트를 추가하여 실행 중인 서비스가 커밋된 스펙과 일치하는지 확인하세요. 엔드포인트가 선언되지 않은 필드를 반환하거나 문서화된 필드를 누락시키면 빌드가 실패합니다. 이러한 피드백 루프가 스펙을 단순한 희망적인 문서에서 강제되는 계약으로 변화시킵니다.