오늘도 여러분의 API는 안녕하신가요?: API First Design과 CodeGen 활용하기 | 인프콘2023

인프런 inflearn·인프콘 2023 2023·2023년·

#backend#openapi#api-design#code-generation#contract-first#developer-tooling#collaboration

AI 요약

코드부터 짜고 문서를 나중에 만드는 방식이 낳은 문서 불일치·중복 API·용어 혼선을, OpenAPI 계약을 먼저 합의하는 API First로 해결한 이야기다. 하나의 명세를 단일 진실 공급원으로 삼아 문서·서버/클라이언트 코드·목 서버를 자동 생성하는 흐름과, Swagger에 대한 오해를 바로잡는다.

핵심 포인트

Code First는 작성자마다 다른 설계서, 이중 문서 관리, 문서 갱신 누락으로 인한 코드-문서 불일치, 경로 중복과 용어 불일치라는 다섯 문제를 낳았다
OpenAPI는 info·paths·재사용 components로 경로·메서드·요청·응답·상태 코드를 명시하는 언어 독립 계약이며, 백엔드·프론트가 함께 리뷰한 명세에서 문서·코드·목 서버를 생성해 구현 전 클라이언트 개발을 시작
Swagger는 단순 문서 화면이 아니라 OpenAPI 기반 도구 모음이고, API First는 완벽한 명세를 한 번에 고정하는 게 아니라 구현에서 발견한 문제를 설계로 되돌리는 반복 개선이다. OpenAPI Generator의 Spring 출력은 Mustache 템플릿을 커스터마이징해 팀 스타일에 맞춘다

왜 읽나문서-코드 불일치와 협업 마찰에 시달리는 팀에게 OpenAPI 계약 기반 개발과 CodeGen 커스터마이징의 실전 진입점.

챕터별 상세

010:07 – 3:06

프론트엔드와 백엔드가 겪는 API 고통

프론트엔드는 전달받은 문서와 실제 응답이 다르거나 구현 일정 때문에 명세를 기다리고, 백엔드는 빈 문서에서 형식을 정한 뒤 코드 변경을 매번 반영해야 한다. 사용하지 않는 API가 방치되고 최신 문서가 무엇인지 확신하기 어려워지면서 양쪽 모두 불필요한 확인과 재작업을 반복한다. 발표는 API를 데이터를 전달하는 부수적 수단으로 보던 태도에서 벗어나 협업의 핵심 계약으로 다루게 된 경험을 출발점으로 삼는다.

위키·엑셀 등 작성자마다 다른 설계서가 일관성을 잃고, 초기 설계 문서와 코드에서 생성한 최종 문서를 두 번 관리하면서 어느 것이 유효한지 혼란이 생겼다. 구현을 먼저 고친 뒤 문서 갱신을 빼먹으면 변경이 구두로만 전달되고 시간이 지나 코드와 API 문서가 어긋난다. 명세보다 코드에 집중한 결과 같은 기능의 경로가 중복되거나 팀마다 같은 개념에 다른 이름을 사용해 지속적인 의사소통 비용이 발생했다.

API를 이해관계자가 합의하고 어느 쪽도 위반해서는 안 되는 계약으로 보고 경로·메서드·요청·응답과 상태 코드를 명시한다. 언어에 독립적인 HTTP API 표준 인터페이스인 OpenAPI Specification은 info, paths, 재사용 가능한 components로 이 계약의 필수 구조를 제공한다. API First Design은 이 명세 기반 계약을 구현보다 우선해 함께 설계하는 방식이며 Swagger·Postman·Apigee 같은 도구 생태계가 이를 활용한다.

백엔드와 프론트엔드가 요구사항을 분석해 계약을 만들고 함께 리뷰한 뒤, 같은 OpenAPI 명세에서 문서와 서버·클라이언트 코드, 목 서버를 자동 생성한다. 구현 전에 목 서버로 클라이언트 개발을 시작하고 변경 시 계약부터 수정하므로 설계서와 최종 문서가 하나로 유지되며 코드와 문서의 불일치도 구조적으로 줄어든다. Git 버전 이력과 공통 문서를 단일 진실 공급원으로 삼고 URL·용어·스키마를 함께 토론해 팀 사이의 맥락과 API 품질을 높인다.

Swagger는 단순 문서 화면이 아니라 OpenAPI에서 출발한 도구 모음이며, 본래 의도한 자동화도 코드 어노테이션보다 명세를 기반으로 한다. API First는 처음부터 완벽한 명세를 고정하는 절차가 아니라 구현에서 발견한 문제를 설계로 되돌려 계약을 반복 개선하고 비즈니스 가치를 먼저 생각하는 방식이다. OpenAPI Generator의 기본 Spring 출력이 팀 스타일과 맞지 않으면 Mustache 템플릿을 커스터마이징해 불필요한 어노테이션을 제거할 수 있으며, 예제 저장소로 직접 시작하는 방법까지 제공한다.