TypeScript 쓰면서 OpenAPI Generator 는 안 쓴다고?

매드업이 RESTful API 를 쓰는 프론트엔드에서 API 스펙 변경을 타입으로 따라가지 못하는 문제를, Swagger 의 OpenAPI Generator 로 푼 방법을 소개한다. GraphQL 이 근본적 대안이지만 도입 비용과 학습 장벽이 커, REST 를 유지하면서 진입장벽이 낮은 대안으로 타입 자동 생성을 택했다.

핵심 포인트

문제는 API 오사용으로 인한 런타임 오류다. 로직 결함이 아니라 프론트와 백엔드가 기대한 데이터 형태가 어긋나서 생기며, 그때마다 추가 대화와 협의가 개발 비용을 잡아먹는다.
TypeScript 로 API 스펙을 손으로 타입화하면 막을 수 있지만, API 가 수십 개를 넘고 비즈니스 요건에 따라 자주 바뀌면 일일이 재정의하는 것이 사실상 불가능해진다.
GraphQL 은 타입 없는 API 에 타입을 입힌다는 점에서 TypeScript 가 JavaScript 에 한 일과 같지만, 학습 장벽에 더해 프론트와 백엔드, 여러 이해당사자의 합의가 필요해 성장세가 더디다고 본다.
대안은 OAS 규격으로 작성된 API 스펙에서 클라이언트 타입을 자동 생성하는 OpenAPI Generator 다.
생성된 타입을 API 정의에 그대로 가져다 쓰면 스펙 변경을 빠르게 감지하고 오사용을 크게 줄일 수 있다.

상세 정리

Swagger 는 RESTful API 를 일관되게 설계하고 개발하는 표준과 자동화 도구를 제공하는 오픈소스 프로젝트이고, 그 표준이 OpenAPI Specification 즉 OAS 다.
OpenAPI Generator 는 그 도구들 중 하나로 OAS 기반 API 스펙에서 클라이언트에서 쓸 수 있는 타입을 만들어준다. 다양한 언어를 지원하지만 이 글은 TypeScript 프론트엔드 경우만 다룬다.
설치는 npm 으로 openapi-generator-cli 를 개발 의존성에 넣는 방식이고, Homebrew 나 docker 로도 가능하다.
설정은 프로젝트 루트에 openapi.json 을 두고 modelPackage 와 모델·API 분리 옵션을 지정한다.
실행 스크립트는 package.json 에 넣는다. API 문서 URL 을 입력으로, generator 를 typescript-axios 로, 출력 디렉터리와 설정 파일을 지정하는 형태다.
생성된 모델은 지정한 폴더에 만들어지며, 필자는 필요한 타입만 소스 경로로 자동 복사되게 설정해 코드에서 참조한다.
axios 기반 API 호출 함수도 함께 생성되지만, 필자는 그대로 쓰기에 적합하지 않다고 보고 사용하지 않는다. 입력과 출력 타입만 가져다 쓴다.
함정도 하나 적는다. 백엔드에서 enum 타입을 한글로 정의하면 생성된 모델에 오류가 생길 수 있어 주의가 필요하다.
결론은 GraphQL 만큼 강력하지 않아도 Swagger 가 프론트와 백엔드의 API 스펙 커뮤니케이션을 생산적으로 만들어준다는 것이다.