OpenAPI-first vs 코드-first API 개발: 핵심 트레이드오프

이 논쟁이 해결하려는 실제 문제

OpenAPI-first와 코드-first 논쟁은 단순한 취향 문제가 아니다. 핵심은 API가 주장하는 것과 실제 동작 사이에 천천히 생기는 괴리를 막는 것이다.

OpenAPI-first는 먼저 API 계약(엔드포인트, 입력, 출력, 오류)을 OpenAPI 명세로 작성한 다음 서버와 클라이언트를 그에 맞춰 구현하는 방식이다. 코드-first는 먼저 코드로 API를 구현하고, 구현에서 OpenAPI 명세와 문서를 생성하거나 작성하는 방식이다.

팀이 이 문제로 논쟁하는 이유는 고통이 나중에 드러나기 때문이다. 보통은 백엔드의 "작은" 변경 이후 클라이언트 앱이 깨지거나, 문서가 더 이상 서버의 동작을 설명하지 못하거나, 엔드포인트마다 검증 규칙이 달라지거나, 사람들로 하여금 추측하게 만드는 모호한 400 오류가 발생하고 "어제는 됐었는데"로 시작하는 지원 티켓이 늘어날 때다.

단순한 예를 들면: 모바일 앱이 phoneNumber를 보내는데 백엔드가 필드명을 phone으로 바꿨다. 서버는 일반적인 400을 응답하고 문서에는 여전히 phoneNumber가 남아 있다. 사용자는 "Bad Request"를 보고 개발자는 로그를 뒤지게 된다.

그래서 실제 질문은: API가 변화할 때 계약, 런타임 동작, 클라이언트 기대치를 어떻게 일치시킬 것인가이다.

이 비교는 일상 업무에 영향을 주는 네 가지 결과에 집중한다: 속도(지금 배포하는 속도와 시간이 지나도 유지되는 속도), 일관성(계약·문서·런타임 동작의 일치), 클라이언트 생성(명세가 시간을 절약하고 실수를 막을 때), 그리고 검증 오류(“잘못된 입력”을 사용자가 이해하고 조치할 수 있는 메시지로 바꾸는 방법).

두 가지 워크플로우: OpenAPI-first와 코드-first의 일반적 흐름

OpenAPI-first는 계약에서 시작한다. 누군가가 엔드포인트 코드를 작성하기 전에 팀이 경로, 요청 및 응답 모양, 상태 코드, 오류 형식을 합의한다. 아이디어는 간단하다: API가 어떻게 보여야 하는지 결정한 다음 그것에 맞춰 구축한다.

일반적인 OpenAPI-first 흐름:

• OpenAPI 명세 초안 작성(엔드포인트, 스키마, 인증, 오류)
• 백엔드·프론트엔드·QA와 검토
• 스텁을 생성하거나 명세를 진실의 출처로 공유
• 명세에 맞춰 서버 구현
• 계약에 따라 요청과 응답을 검증(테스트나 미들웨어)

코드-first는 순서를 뒤집는다. 엔드포인트를 코드로 만들고 나서 주석이나 코멘트를 추가해 도구가 나중에 OpenAPI 문서를 생성하도록 한다. 탐색 단계에서는 별도의 명세를 먼저 업데이트하지 않고도 로직과 라우트를 바로 바꿀 수 있어 빠르게 느껴질 수 있다.

일반적인 코드-first 흐름:

• 코드에서 엔드포인트와 모델 구현
• 스키마, 파라미터, 응답에 대한 주석 추가
• 코드베이스에서 OpenAPI 명세 생성
• 출력물 조정(보통 주석을 다듬음)
• 생성된 명세를 문서와 클라이언트 생성에 사용

어디서 괴리가 생기는가는 워크플로우에 따라 다르다. OpenAPI-first에서는 명세가 일회성 설계 문서로 취급되어 변경 이후 업데이트되지 않을 때 괴리가 생긴다. 코드-first에서는 구현이 변경되지만 주석이 업데이트되지 않아 생성된 명세가 그럴듯하게 보이지만 실제 동작(상태 코드, 필수 필드, 엣지 케이스)은 조용히 달라질 때 괴리가 생긴다.

간단한 규칙: 계약-우선은 명세가 무시될 때, 코드-우선은 문서가 뒷전일 때 괴리가 생긴다.

속도: 지금 빠르게 느껴지는 것과 시간이 지나도 빠른 것

속도는 한 가지가 아니다. "다음 변경을 얼마나 빨리 배포할 수 있나"와 "6개월 후에도 얼마나 빨리 계속 배포할 수 있나"가 있다. 두 접근법은 어느 시점엔가 속도에서 우열이 뒤바뀌는 경향이 있다.

초기에는 코드-first가 더 빠르게 느껴질 수 있다. 필드를 추가하고 애플리케이션을 실행하면 바로 동작한다. API가 아직 유동적일 때 그 피드백 루프는 매우 강력하다. 비용은 다른 사람들이 API에 의존하기 시작하면 드러난다: 모바일, 웹, 내부 도구, 파트너, QA 등.

OpenAPI-first는 첫날에는 느릴 수 있다. 엔드포인트가 존재하기 전에 계약을 작성하기 때문이다. 그러나 재작업이 줄어든다는 보상이 있다. 필드명이 바뀌면 그 변경은 클라이언트를 깨뜨리기 전에 가시화되고 검토될 수 있다.

장기적인 속도는 주로 반복 작업을 피하는 것에 달려 있다: 팀 간의 오해가 줄고, 일관성 없는 동작 때문에 생기는 QA 사이클이 줄고, 계약이 명확한 출발점이 되어 온보딩이 빨라지고, 변경이 명시적이어서 승인 절차가 깔끔해진다.

팀을 느리게 만드는 것은 코드 타이핑 자체가 아니다. 재작업이다: 클라이언트 재구축, 테스트 재작성, 문서 업데이트, 불분명한 동작 때문에 오는 지원 티켓.

내부 도구와 모바일 앱을 병행 개발한다면 계약-우선은 두 팀이 동시에 움직일 수 있게 해준다. 요구사항이 바뀔 때 플랫폼이 변경을 반영해 코드를 재생성하는 경우(예: AppMaster) 같은 원리가 오래된 결정을 계속 끌고 가지 않도록 도와준다.

일관성: 계약·문서·동작을 일치시키기

대부분의 API 문제는 기능이 부족해서가 아니다. 불일치 때문이다: 문서는 한 가지를 말하는데 서버는 다른 동작을 하고, 클라이언트는 잡아내기 어려운 방식으로 깨진다.

핵심 차이는 "진실의 출처(source of truth)"다. 계약-우선 흐름에서는 명세가 기준이며 다른 모든 것은 그것을 따라야 한다. 코드-우선 흐름에서는 실행 중인 서버가 기준이며 명세와 문서는 사후에 따라오는 경우가 많다.

명명, 타입, 필수 필드에서 괴리가 가장 먼저 드러난다. 코드에서 필드명이 바뀌었지만 명세는 그대로인 경우, 불리언이 한 클라이언트의 전송 방식 때문에 문자열이 되는 경우, 한 필드가 선택에서 필수로 바뀌었지만 오래된 클라이언트는 이전 형태를 계속 보내는 경우 등. 각 변경은 작아 보일 수 있지만 합쳐지면 지속적인 지원 부담을 만든다.

일관성을 유지하는 실용적인 방법은 절대 벗어나면 안 되는 것을 정하고 이를 워크플로우에서 강제하는 것이다:

• 요청과 응답에 대해 하나의 정규화된 스키마를 사용(필수 필드와 포맷 포함).
• 깨지는 변경은 의도적으로 버전 관리. 필드 의미를 조용히 바꾸지 않기.
• 명명 규칙(예: snake_case vs camelCase)을 합의하고 모든 곳에 적용.
• 예제는 단순 문서가 아니라 실행 가능한 테스트 케이스로 다루기.
• 계약 불일치가 빠르게 실패하도록 CI에 계약 검사 추가.

예제는 사람들이 복사해서 쓰는 것이므로 특히 신경 써야 한다. 예제가 필수 필드가 빠진 형태라면 실제 트래픽에서 동일한 누락이 발생한다.

클라이언트 생성: OpenAPI가 가장 이득일 때

생성된 클라이언트는 동일 API를 여러 팀(또는 앱)이 소비할 때 가장 중요하다. 그때 논쟁은 취향 문제가 아니라 시간 절약과 실수 방지가 된다.

생성할 수 있는 것들(그리고 왜 도움이 되는가)

튼튼한 OpenAPI 계약에서 생성할 수 있는 것은 문서 이상이다. 일반적인 출력물로는 실수를 조기에 잡아주는 타입화된 모델, 웹·모바일용 클라이언트 SDK(메서드, 타입, 인증 훅), 구현을 맞추는 서버 스텁, QA와 지원을 위한 테스트 픽스처 및 샘플 페이로드, 백엔드가 완성되기 전에 프론트엔드 작업을 가능하게 하는 목(mock) 서버 등이 있다.

이는 웹 앱, 모바일 앱, 내부 도구가 동일한 엔드포인트를 호출하는 경우에 가장 빠르게 보상한다. 작은 계약 변경을 모든 곳에서 재생성하면 손으로 다시 구현하는 대신 자동으로 반영된다.

생성된 클라이언트는 특수한 커스터마이징(특별한 인증 흐름, 재시도, 오프라인 캐시, 파일 업로드 등)이 필요하거나 생성기가 팀이 선호하지 않는 코드를 만들면 짜증스러울 수 있다. 일반적인 절충안은 코어 타입과 저수준 클라이언트를 생성한 뒤 얇은 수작업 래퍼로 감싸서 앱 요구에 맞추는 것이다.

생성된 클라이언트가 조용히 깨지는 것을 막기

모바일과 프론트엔드 앱은 예기치 않은 변경을 싫어한다. "어제는 컴파일됐는데" 실패를 피하려면:

• 계약을 버전 관리된 산출물로 다루고 변경을 코드처럼 검토.
• 깨지는 변경(필드 제거, 타입 변경)을 실패시키는 CI 검사 추가.
• 추가적인(선택적) 변경을 선호하고 제거 전에 먼저 deprecated 표기.
• 오류 응답을 일관되게 유지해 클라이언트가 예측 가능하게 처리하도록.

운영팀이 웹 관리자 패널을 사용하고 현장 인력이 네이티브 앱을 사용한다면 동일한 OpenAPI 파일로부터 Kotlin/Swift 모델을 생성하면 필드명 불일치와 누락된 enum을 방지할 수 있다.

검증 오류: "400"을 사용자가 이해할 수 있게 바꾸기

대부분의 "400 Bad Request" 응답은 나쁜 것이 아니다. 필수 필드 누락, 숫자를 텍스트로 보냄, 잘못된 날짜 포맷 등 정상적인 검증 실패다. 문제는 원시 검증 출력이 종종 개발자용 메모처럼 보여 사용자가 고칠 수 있는 형태가 아니라는 점이다.

가장 많은 지원 티켓을 생성하는 실패는 필수 필드 누락, 잘못된 타입, 잘못된 포맷(날짜, UUID, 전화번호, 통화), 허용 범위를 벗어난 값, 허용되지 않은 값(허용된 리스트에 없는 상태 등)이다.

두 워크플로우 모두 같은 결과를 낳을 수 있다: API는 문제를 알고 있지만 클라이언트는 "invalid payload." 같은 모호한 메시지를 받는다. 이를 고치는 것은 워크플로우 문제라기보다 명확한 오류 형식과 일관된 매핑 규칙을 채택하는 문제다.

단순한 패턴: 응답을 일관되게 유지하고 모든 오류를 조치 가능하게 만들라. (1) 어떤 필드가 잘못되었는지, (2) 왜 잘못되었는지, (3) 어떻게 고치면 되는지를 반환하라.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Please fix the highlighted fields.",
    "details": [
      {
        "field": "email",
        "rule": "format",
        "message": "Enter a valid email address."
      },
      {
        "field": "age",
        "rule": "min",
        "message": "Age must be 18 or older."
      }
    ]
  }
}

이 형식은 UI 폼에 깔끔하게 매핑된다: 해당 필드를 하이라이트하고 필드 옆에 메시지를 표시하며, 상단에는 사용자가 놓친 항목에 대한 짧은 메시지를 둔다. 핵심은 내부 문구(예: "failed schema validation")를 노출하지 않고 사용자가 바꿀 수 있는 언어로 표현하는 것이다.

어디서 검증할지와 중복 규칙을 피하는 방법

검증은 각 계층이 명확한 역할을 가질 때 가장 잘 작동한다. 모든 계층이 모든 규칙을 강제하려 하면 중복 작업, 혼란스러운 오류, 웹·모바일·백엔드 간 규칙 괴리가 생긴다.

실용적인 분리는 다음과 같다:

• 에지(예: API 게이트웨이 또는 요청 핸들러): 형태와 타입 검증(필수 필드 누락, 잘못된 포맷, enum 값)을 처리. OpenAPI 스키마가 잘 맞는 곳이다.
• 서비스 레이어(비즈니스 로직): 실제 규칙 검증(권한, 상태 전이, "종료일은 시작일 이후여야 한다", "할인은 활성 고객에게만 적용" 등).
• 데이터베이스: 결코 위반되어서는 안 되는 제약(유니크 제약, 외래 키, not-null)을 강제. 데이터베이스 오류는 안전망으로 취급하라, 주요 사용자 경험 수단으로 삼지 말라.

웹과 모바일에서 동일한 규칙을 유지하려면 하나의 계약과 하나의 오류 형식을 사용하라. 클라이언트가 빠른 검사(예: 필수 필드 체크)를 하더라도 API를 최종 판정자로 삼아야 한다. 그래야 규칙이 바뀌었다고 모바일 업데이트가 꼭 필요하지 않다.

간단한 예: API가 phone을 E.164 형식으로 요구한다면 에지에서 잘못된 포맷을 일관되게 거부할 수 있다. 하지만 "전화번호는 하루에 한 번만 변경 가능" 같은 규칙은 사용자 이력에 의존하므로 서비스 레이어에 있어야 한다.

로그에 남길 것과 사용자에게 보여줄 것

개발자를 위해서 디버그에 충분한 정보를 기록하라: 요청 ID, 사용자 ID(가능하면), 엔드포인트, 검증 규칙 코드, 필드명, 원시 예외 등. 사용자에게는 짧고 조치 가능한 정보를 제공하라: 어떤 필드가 실패했는지, 무엇을 고쳐야 하는지, 가능한 경우 예시를 제공하라. 내부 테이블명, 스택 트레이스, "사용자가 역할 X에 속하지 않음" 같은 정책 세부사항은 노출하지 마라.

단계별: 하나의 접근법을 선택하고 도입하기

팀이 두 접근법으로 계속 논쟁한다면 시스템 전체를 한 번에 결정하려 하지 마라. 작고 위험이 낮은 조각을 골라 실험하라. 한 번의 파일럿에서 배우는 것이 수주간의 의견 교환보다 더 많은 것을 알려줄 것이다.

범위를 좁게 시작하라: 실제로 사람들이 사용하는 하나의 리소스와 1~3개의 엔드포인트(예: "티켓 생성", "티켓 목록", "상태 업데이트"). 프로덕션에 가깝게 해서 실제 고통을 느끼되, 방향을 바꾸기 쉬울 만큼 작게 유지하라.

실용적인 롤아웃 계획

1. 파일럿을 선택하고 "완료"의 정의를 정한다(엔드포인트, 인증, 주요 성공·실패 케이스).

2. OpenAPI-first로 간다면 서버 코드를 작성하기 전에 스키마, 예제, 표준 오류 형식을 먼저 작성하라. 명세를 공유된 합의로 다루라.

3. 코드-first로 간다면 핸들러를 먼저 만들고 명세를 내보낸 뒤(생성된 명세) 이름, 설명, 예제, 오류 응답을 정리해 계약처럼 읽히게 하라.

4. 변경이 의도적임을 보장하는 계약 검사를 추가하라: 명세가 하위 호환성을 깨면 빌드를 실패시키거나 생성된 클라이언트가 계약에서 벗어나면 알리기.

5. 실제 클라이언트(웹 UI나 모바일 앱 등) 하나에 배포해 마찰 포인트를 수집하고 규칙을 업데이트하라.

no-code 플랫폼을 사용 중이라면(예: AppMaster) 파일럿은 더 작게 할 수 있다: 데이터 모델을 정의하고 엔드포인트를 정한 뒤 같은 계약으로 웹 관리자 화면과 모바일 뷰를 구동한다. 도구 자체보다 중요한 것은 습관이다: 하나의 진실의 출처, 변경 시마다 테스트되는 프로세스, 실제 페이로드와 일치하는 예제.

느려지거나 지원 티켓을 늘리는 흔한 실수

대부분의 팀은 "잘못된" 쪽을 골라 실패하는 것이 아니다. 실패하는 이유는 계약과 런타임을 별개의 세계로 취급한 다음 몇 주 동안 그것을 조정하느라 시간을 쓰기 때문이다.

고전적인 함정은 OpenAPI 파일을 "멋진 문서"로 작성해 놓고 이를 강제하지 않는 것이다. 명세가 흐려지고 클라이언트는 잘못된 진실에서 생성되며 QA가 늦게 불일치를 발견한다. 명세를 공개한다면 테스트 가능하게 만들어라: 요청과 응답을 그것에 대해 검증하거나 동작을 맞추는 서버 스텁을 생성하라.

또 다른 지원 티켓 공장은 버전 규칙 없이 클라이언트를 생성하는 것이다. 모바일 앱이나 파트너 클라이언트가 생성된 SDK의 최신 버전으로 자동 업데이트하면 작은 변경(예: 필드명 변경)이 조용한 파괴로 이어진다. 생성된 클라이언트는 버전을 고정하고, 변경 정책을 명확히 게시하며, 깨지는 변경은 의도적인 릴리스로 다뤄라.

오류 처리는 작은 불일치가 큰 비용을 만드는 곳이다. 각 엔드포인트가 다른 400 형식을 반환하면 프론트엔드는 일회성 파서와 "문제가 발생했습니다" 같은 일반화된 메시지로 일관된 처리를 할 수 없게 된다. 오류를 표준화해 클라이언트가 항상 유용한 텍스트를 표시할 수 있게 하라.

대부분의 느려짐을 막는 빠른 점검:

• 하나의 진실의 출처를 유지하라: 명세에서 코드를 생성하거나 코드에서 명세를 생성하되 항상 일치하는지 검증하라.
• 생성된 클라이언트를 API 버전에 고정하고 무엇이 깨지는 변경인지 문서화하라.
• 동일한 오류 형식을 everywhere 사용(같은 필드와 같은 의미)하고 안정적인 오류 코드를 포함하라.
• 까다로운 필드(날짜 포맷, enum, 중첩 객체)에 대한 예제를 추가하라. 단순 타입 정의만 두지 마라.
• 경계에서 검증(게이트웨이나 컨트롤러)해 비즈니스 로직이 정제된 입력을 가정하게 하라.

결정을 내리기 전 빠른 점검 목록

방향을 선택하기 전에 팀의 실제 마찰 지점을 드러내는 몇 가지 작은 검사를 해보라.

간단한 준비성 체크리스트

대표 엔드포인트 하나(요청 바디, 검증 규칙, 몇 가지 오류 케이스)를 골라 아래에 "예"라고 답할 수 있는지 확인하라:

• 계약에 대한 명확한 오너가 있고 변경 전 검토 단계가 있다.
• 오류 응답이 엔드포인트 전반에 걸쳐 동일한 형태를 갖고 있는가: 동일한 JSON 구조, 예측 가능한 오류 코드, 비기술자가 조치할 수 있는 메시지.
• 계약에서 클라이언트를 생성해 실제 UI 화면 하나에서 타입을 수작업으로 고치지 않고 사용할 수 있는가.
• 배포 전에 깨지는 변경이 잡히는가(계약 diff를 CI에서 검사하거나 응답이 스키마와 일치하지 않으면 테스트가 실패).

오너십과 리뷰에서 걸린다면 시간이 지나면서 "거의 맞는" API가 배포될 것이다. 오류 형식에서 걸린다면 사용자는 "400 Bad Request"만 보고 "이메일이 빠졌음"이나 "시작일이 종료일보다 이전이어야 함" 같은 구체적 메시지를 보지 못해 지원 티켓이 쌓인다.

실용적인 테스트: 고객 생성 같은 폼 화면 하나를 골라 일부러 세 가지 잘못된 입력을 제출해 보라. 그 검증 오류들을 특수 케이스 코드 없이 필드 수준의 명확한 메시지로 바꿀 수 있다면 확장 가능한 접근에 근접한 것이다.

예시 시나리오: 내부 도구와 모바일 앱이 같은 API를 쓰는 경우

작은 팀이 먼저 운영용 내부 관리자 도구를 만들고 몇 달 후 현장 직원을 위한 모바일 앱을 만든다. 둘 다 같은 API를 사용: 작업 생성, 상태 업데이트, 사진 첨부 등.

코드-first 접근에서는 관리자 도구가 초기에 잘 동작하는 경우가 많다. 웹 UI와 백엔드가 함께 바뀌기 때문이다. 문제는 모바일 앱이 나중에 배포될 때 드러난다. 그 사이에 엔드포인트가 흘러갔다: 필드명이 바뀌고 enum 값이 바뀌고 어떤 엔드포인트는 선택이었던 파라미터를 필수로 바꿨다. 모바일 팀은 이런 불일치를 늦게 발견하고 무작위 400으로 고생하며 사용자는 "무언가 잘못됨"만 보게 되어 지원 티켓이 쌓인다.

계약-우선 설계를 쓰면 관리자 웹과 모바일 앱 모두 처음부터 동일한 형태, 이름, 규칙을 신뢰할 수 있다. 구현 세부가 바뀌더라도 계약이 공동 참조점으로 남는다. 클라이언트 생성의 이점도 더 크게 나타난다: 모바일 앱은 직접 타입과 요청 모델을 생성해 수작업으로 작성하거나 필드가 필수인지 추측할 필요가 없다.

검증은 사용자가 차이를 가장 크게 느끼는 부분이다. 예를 들어 모바일 앱이 국가 코드를 빼고 전화번호를 보냈다고 하자. 원시 응답 "400 Bad Request"는 쓸모가 없다. 사용자 친화적 오류 응답은 플랫폼 전반에 일관되게 다음과 같이 표현될 수 있다:

• code: INVALID_FIELD
• field: phone
• message: Enter a phone number with country code (example: +14155552671).
• hint: Add your country prefix, then retry.

이 한 가지 변경이 백엔드 규칙을 실제 사용자가 따를 수 있는 명확한 다음 단계로 바꾼다. 관리자 도구든 모바일이든 상관없다.

다음 단계: 파일럿 선택, 오류 표준화, 자신 있게 구축하기

실용적인 규칙: API가 여러 팀에 공유되거나 웹·모바일·파트너를 지원해야 한다면 OpenAPI-first를 선택하라. 하나의 팀이 전부 소유하고 있고 API가 매일 변경되는 탐색 단계라면 코드-first를 선택하되, 그래도 코드에서 명세를 생성해 계약을 잃지 않도록 하라.

계약이 어디에 있고 어떻게 검토되는지 결정하라. 가장 단순한 설정은 OpenAPI 파일을 백엔드와 같은 리포지토리에 두고 모든 변경 검토에서 포함시키는 것이다. 명확한 오너를 지정(보통 API 오너나 테크 리드)하고 앱을 깨뜨릴 수 있는 변경에 대해 적어도 한 명의 클라이언트 개발자를 리뷰에 포함하라.

빠르게 진행하면서 모든 조각을 손으로 코딩하고 싶지 않다면 계약 구동 접근은 no-code 플랫폼과도 맞는다. 예를 들어 AppMaster (appmaster.io)는 동일한 기본 모델에서 백엔드 코드와 웹/모바일 앱을 생성할 수 있어 요구사항이 바뀔 때 API 동작과 UI 기대치가 일치하기 쉽다.

작게 시작해 확장하라:

• 실제 사용자가 있는 2~5개의 엔드포인트와 최소 하나의 클라이언트(웹 또는 모바일)를 선택하라.
• 오류 응답을 표준화해 "400"을 필드별 명확 메시지(어떤 필드가 실패했는지, 무엇을 고쳐야 하는지)로 바꿔라.
• 워크플로우에 계약 검사를 추가하라(깨지는 변경에 대한 diff 검사, 기본 린팅, 응답이 계약과 일치하는지 검증하는 테스트).

이 세 가지를 잘 하면 나머지 API는 더 쉽게 구축되고 문서화되며 지원하기 쉬워진다.