193. OpenAPI Specification - Swagger 기반 API 계약 표준

핵심 인사이트 (3줄 요약)

본질: OpenAPI Specification (OAS)은 HTTP 기반 API (Application Programming Interface)의 경로, 파라미터, 요청 본문, 응답, 보안 규칙을 기계가 읽을 수 있는 계약 문서로 정의하는 표준이다.

가치: 문서·테스트·Mock Server·SDK 생성·계약 검증을 하나의 스펙에서 파생시켜, 백엔드와 프론트엔드 사이의 명세 불일치 비용을 크게 줄인다.

판단 포인트: OAS는 단순 문서 도구가 아니라 설계 거버넌스 수단이므로, 공개 API나 다팀 협업 환경일수록 Design First가 유리하고, 내부 단기 개발이라도 최소한의 계약 자동화는 유지해야 한다.

Ⅰ. 개요 및 필요성

OpenAPI Specification은 REST 계열 HTTP API를 표준 구조로 기술하는 명세 언어다. 개발자는 경로, 메서드, 스키마, 인증 방식, 상태 코드를 YAML (YAML Ain't Markup Language) 또는 JSON 형식으로 선언하고, 다양한 도구가 이를 읽어 문서와 코드 산출물을 자동 생성한다. 즉 OAS의 본질은 "설명서"보다 실행 가능한 계약서에 가깝다.

이 개념이 중요해진 이유는 API 수가 늘수록 사람 손으로 관리하는 엑셀·위키 문서가 빠르게 낡기 때문이다. 백엔드가 필드명을 userNo로 바꾸고 문서가 userId에 머무르면 프론트엔드는 잘못된 요청을 보내고, QA는 어디가 진실인지 확인하느라 시간을 잃는다. 마이크로서비스와 공개 API 생태계가 커질수록 이런 계약 드리프트는 장애와 재작업의 직접 원인이 된다.

또한 OAS는 팀 간 병렬 개발을 가능하게 한다. 서버가 완성되기 전에도 계약만 확정되면 프론트엔드는 Mock 응답으로 화면을 개발하고, 테스트 자동화는 스펙을 기준으로 유효성을 검증할 수 있다. 그래서 OAS는 개발 문서가 아니라 협업 속도를 높이는 공통 언어로 봐야 한다.

📢 섹션 요약 비유: OAS는 요리사가 머릿속으로만 레시피를 알고 있는 식당이 아니라, 재료·조리 순서·알레르기 정보까지 표준 카드로 적어 주방과 홀 직원이 동시에 같은 메뉴를 준비하는 체계와 같다.

Ⅱ. 아키텍처 및 핵심 원리

OAS 문서는 보통 paths, parameters, requestBody, responses, components.schemas, securitySchemes 같은 구역으로 나뉜다. 핵심은 단순히 엔드포인트 목록을 적는 것이 아니라, 각 요청과 응답의 구조를 재사용 가능한 스키마로 정의해 계약을 일관되게 유지하는 데 있다. 이 스펙은 Swagger UI, code generator, mock server, gateway validator 같은 도구 체인으로 이어진다.

구성 요소	역할	실무 포인트
`paths`	URL과 메서드 정의	리소스 경계와 행위가 명확해야 함
`parameters` / `requestBody`	입력 계약 정의	필수 여부, 타입, 예시를 명확히 기술
`responses`	상태 코드와 응답 구조 정의	오류 모델까지 통일해야 운영성이 좋아짐
`components.schemas`	공통 데이터 모델 재사용	DTO 중복과 불일치 방지
`securitySchemes`	인증·인가 방식 명세	OAuth 2.0, API Key, Bearer 규칙 표준화

아래 흐름은 OAS 하나가 여러 개발 산출물로 연결되는 구조를 보여준다.

┌──────────────────────────────────────────────────────────────────────┐
│ OAS lifecycle: one contract -> many artifacts                       │
├──────────────────────────────────────────────────────────────────────┤
│ OAS YAML/JSON -> Lint/Review -> Mock Server -> SDK/Docs -> Runtime  │
│        │                                  │                         │
│        └──────────── Contract Test <──────┘                         │
└──────────────────────────────────────────────────────────────────────┘

여기서 Swagger는 역사적으로 OAS의 전신이자, 현재는 Swagger UI·Swagger Codegen 같은 도구 생태계를 가리키는 경우가 많다. 즉 OpenAPI는 표준 규격, Swagger는 이를 활용하는 대표 도구군으로 구분하면 헷갈리지 않는다. 설계 품질은 화면이 예쁜가보다 스펙이 변경 관리와 검증에 실제로 연결되는가에 달려 있다.

📢 섹션 요약 비유: OAS는 건물 도면이고, Swagger UI는 그 도면을 보여 주는 모델하우스다. 모델하우스가 멋져도 도면이 부실하면 실제 건물은 제대로 지어질 수 없다.

Ⅲ. 비교 및 연결

OAS를 둘러싼 대표 논점은 Design First와 Code First의 차이다. Design First는 계약을 먼저 합의하고 구현이 뒤따르며, Code First는 서버 코드를 기준으로 스펙을 추출한다. 둘 다 쓸 수 있지만 협업 구조와 API 성격에 따라 장단점이 분명하게 갈린다.

항목	Design First	Code First	수기 문서 중심
출발점	스펙 합의	구현 코드	위키, 엑셀, 문서 편집
장점	병렬 개발, 계약 검토, Mock 활용 용이	구현과 스펙 동기화 쉬움	시작은 빠름
약점	초기 설계 품질이 낮으면 재작업	코드 구조가 곧 계약을 왜곡할 수 있음	드리프트와 누락이 잦음
적합 사례	공개 API, 다수 팀 협업	내부 API, 빠른 프로토타입	장기 운영에는 부적합

연결 개념도 중요하다. AsyncAPI는 이벤트 기반 인터페이스 문서화에 특화된 표준이고, GraphQL SDL (Schema Definition Language)은 GraphQL 전용 계약 체계다. 즉 OAS는 "모든 인터페이스의 범용 표준"이 아니라 HTTP 요청/응답 API에 최적화된 계약 모델이다. 그래서 웹훅, 이벤트 버스, GraphQL을 함께 쓰는 조직이라면 OAS 하나로 모든 것을 설명하려 하기보다 인터페이스 유형별 표준을 병행해야 한다.

📢 섹션 요약 비유: Design First는 건축 전에 설계도부터 확정하는 방식이고, Code First는 먼저 집을 짓고 도면을 다시 그리는 방식이다. 둘 다 가능하지만 공사가 커질수록 먼저 도면을 맞추는 쪽이 사고가 적다.

Ⅳ. 실무 적용 및 기술사 판단

실무에서 OAS를 잘 쓰려면 문서 생성에서 끝내지 말고 배포 파이프라인에 묶어야 한다. 예를 들어 Pull Request 단계에서 스펙 변경 diff를 검토하고, breaking change lint를 돌리며, contract test와 mock test를 함께 수행해야 한다. 그래야 OAS가 살아 있는 계약이 된다.

체크리스트

필수 필드 제거, 타입 변경, 응답 코드 삭제 같은 breaking change를 자동으로 탐지하는가?
오류 응답 형식, 페이지네이션, 날짜 형식, 인증 헤더를 공통 규칙으로 통일했는가?
예시 요청/응답과 실제 구현이 contract test로 검증되는가?
공개 API라면 버전 전략(/v1, header versioning 등)과 deprecation 정책이 명시되어 있는가?

채택 판단

적극 채택: 외부 파트너 공개 API, 다수 프론트엔드 소비자, 모바일 SDK 자동 생성, 여러 팀이 동시에 개발하는 환경
부분 채택: 내부 단일 팀 API라도 배포 자동화와 테스트 기반 계약 검증이 필요한 환경
주의: 스펙을 적기만 하고 리뷰·테스트·코드 생성에 연결하지 않는 경우

결국 기술사 답안에서는 OAS를 "Swagger 문서 화면"으로 축소하면 안 된다. 핵심은 API 계약을 설계·개발·테스트·운영 전 과정에서 재사용하도록 만드는 표준화 체계라는 점이다.

📢 섹션 요약 비유: OAS를 잘 쓰는 팀은 메뉴판만 예쁘게 인쇄하는 식당이 아니라, 주문서·주방 프린터·재고표가 모두 같은 메뉴 코드로 연결된 식당이다. 이름만 같고 내부 코드가 다르면 결국 사고가 난다.

Ⅴ. 기대효과 및 결론

OAS를 정착시키면 API 협업 속도가 빨라지고, 문서 신뢰성이 높아지며, SDK 생성과 테스트 자동화로 반복 작업이 크게 줄어든다. 또한 공개 API 운영에서는 파트너 온보딩 속도와 변경 관리의 품질이 좋아져 생태계 확장에도 유리하다. 즉 OAS의 진짜 효과는 문서 작성 시간 절감보다 계약 비용 절감에 있다.

물론 OAS가 도메인 설계 자체를 대신해 주지는 않는다. 나쁜 리소스 모델, 불명확한 상태 전이, 일관성 없는 오류 정책은 스펙을 써도 그대로 드러난다. 따라서 이 주제는 "문서를 자동 생성하는 도구"가 아니라 API를 제품처럼 관리하기 위한 계약 운영 체계로 기억해야 한다.

📢 섹션 요약 비유: OAS는 예쁜 안내판을 하나 더 붙이는 일이 아니라, 공항의 탑승권·게이트·수하물 태그 번호를 모두 같은 규칙으로 맞추는 작업과 같다. 규칙이 맞아야 사람이 덜 헤맨다.

📌 관련 개념 맵

개념	연결 포인트
Swagger UI	OAS 스펙을 사람이 읽기 쉬운 문서 화면으로 렌더링
Mock Server	구현 전에도 계약 기반 응답을 제공해 병렬 개발 지원
Contract Test	실제 구현이 스펙을 어기지 않는지 자동 검증
AsyncAPI	이벤트 기반 인터페이스 문서화에 특화된 인접 표준
API Gateway	OAS를 바탕으로 라우팅·검증·보안 정책을 자동화할 수 있는 실행 계층

📈 관련 키워드 및 발전 흐름도

수기 API 문서
    │
    ▼
OpenAPI Specification (OAS)
    │
    ▼
Swagger UI · Code Generation
    │
    ▼
Mock Server · Contract Test
    │
    ▼
API 거버넌스 · 변경 관리 자동화

이 흐름은 "문서 표준화 → 자동화 도구화 → 계약 운영 체계"로 성숙하는 과정을 보여준다.

👶 어린이를 위한 3줄 비유 설명

OAS는 가게에서 어떤 음식을 어떻게 주문할 수 있는지 적어 둔 약속 종이예요.
이 종이가 있으면 요리사와 손님이 서로 다른 말을 해서 헷갈릴 일이 줄어요.
컴퓨터는 그 종이를 보고 설명서도 만들고 연습용 가게도 만들 수 있어요.