OpenAPI Generator 실전편: 효율적인 코드를 작성하는 법│인프콘2024

GraphQL·gRPC·tRPC도 자동화를 제공하지만 OpenAPI Generator는 기존 REST 백엔드 스택을 크게 바꾸지 않고 도입할 수 있다는 장점이 있다. Swagger Specification이 OpenAPI Specification으로 이전된 역사와 Swagger Codegen에서 갈라진 프로젝트 관계를 정리해 검색과 도구 선택의 혼동을 줄인다. 생성 과정은 명세, generator 옵션, Mustache·Handlebars 템플릿이라는 세 조정 지점으로 나뉘며 이후 문제도 이 경계에 따라 해결한다.

문서 UI가 관대하게 보여 주던 불완전한 OpenAPI 명세는 코드 생성 단계에서 실패하므로 lint를 CI에 넣어 규칙을 먼저 강제해야 한다. Unicode 클래스·파일 이름의 불일치와 실행할 때마다 모델 순서가 달라지는 문제는 영문 명명 규칙과 결정적인 정렬로 해결해 의미 없는 diff를 막았다. 배열과 중첩 객체의 쿼리 직렬화 방식도 서버 프레임워크와 generator가 모두 지원하는지 확인하고, 명세의 style·explode 설정 또는 팀의 직렬화 도구로 맞춘다.

대부분의 generator가 사용하는 Mustache는 로직 없는 템플릿을 지향해 존재 여부와 반복은 처리하지만 HTTP method 같은 조건식을 자유롭게 만들 수 없다. 따라서 GET만 React Query로 생성하는 것처럼 generator가 제공하지 않는 변수 기반 요구는 템플릿만으로 풀기 어렵고, 필요한 범위를 먼저 확인해야 한다. 팀은 enum을 TypeScript union으로 바꾸고 불필요한 프리픽스를 제거하는 등 지원 가능한 부분만 수정했으며, union edge case가 있는 런타임 검증 옵션은 실제 결과를 보고 껐다.

웹과 React Native 앱이 함께 생성 코드를 쓰도록 결과물을 내부 라이브러리로 배포하고, Conventional Commits를 기준으로 생성과 semantic version 갱신을 자동화했다. 서버 변경과 SDK의 breaking change가 완전히 일치하지는 않지만 버전과 타입 검사 덕분에 영향 범위를 빠르게 찾고 누락을 컴파일 단계에서 드러낼 수 있다. 신규 프로젝트는 전체 자동화를 적용하고 기존 프로젝트는 모델 생성부터 시작해 부담을 낮추는 점진 도입 전략을 권한다.