OpenAPI 명세 하나로 API Gateway와 Lambda를 동시에 배포하는 법

API 문서, 클라이언트 코드, 인프라 설정이 각각 따로 관리되면 어떤 일이 벌어질까요? 셋 중 하나가 업데이트될 때마다 나머지 둘이 뒤처지고, 결국 "문서와 실제 동작이 다르다"는 말이 나오게 돼요. 이 팀은 OpenAPI 명세서를 단일 진실 공급원(single source of truth)으로 삼아서, YAML 파일 하나로 클라이언트 코드 생성부터 AWS 인프라 배포까지 처리하고 있어요.

OpenAPI 사양은 HTTP API를 정의하기 위한 표준화된 명세 언어예요. 특정 프로그래밍 언어에 종속되지 않고, 설계 단계에서 만든 문서가 개발, 테스트, 배포 전 단계에서 기준이 되죠. 단순한 문서화 도구가 아니라 API의 전체 라이프사이클을 연결하는 허브인 셈이에요.

x-amazon-apigateway-integration 한 줄이 엔드포인트와 Lambda를 잇는다

AWS API Gateway는 OpenAPI 명세서를 사용한 REST API 개발을 공식 지원해요. 핵심은 `x-amazon-apigateway-integration` 객체인데, HTTP 엔드포인트를 특정 Lambda 함수로 연결하는 역할이죠. `type`은 Lambda 통합 시 항상 `aws_proxy`, `httpMethod`는 POST, `uri`에는 Lambda ARN을 넣으면 돼요.

주의할 점이 하나 있어요. OpenAPI v3.1.0 명세서에 이 객체를 선언하면 에러가 발생하거든요. v3.0.1까지만 지원하니까 버전 선택에 신경 써야 해요. Terraform으로 필요한 리소스를 배포하면, OpenAPI 명세 하나에서 API 정의와 인프라 구성이 동시에 이뤄지는 구조가 완성돼요.

명세가 곧 코드이고 인프라인 세상

이 접근법의 진짜 가치는 변경 관리에 있어요. API 스펙이 바뀌면 YAML 파일 하나만 수정하면 되고, 그 변경이 클라이언트 코드 생성과 인프라 배포에 자동으로 반영되거든요. "문서와 코드가 다르다"는 고질적인 문제가 구조적으로 해소되는 셈이죠. 물론 모든 프로젝트에 맞는 건 아니에요. API 변경 빈도가 높고 팀 규모가 커질수록 이 방식의 효과가 극대화되지만, 소규모 프로젝트에서는 오히려 초기 설정 비용이 부담될 수 있거든요.