Reese-log
  • About
  • Blog

© 2025 Reese. All rights reserved.

2024년 5월 22일

생산성을 높여주는 고마운 친구 - OpenAPI Generator

#Etc

Restful API 스펙 문서 보면서 Data fetching 함수 작성하다가 endpoint 오타내기.. 저만 경험해봤나요? 😇

어떤 기능을 구현할 때 흔히들 아래와 같은 플로우로 진행하게됩니다.

  • 기획
  • 기획을 기반으로 프론트엔드와 백엔드간 API 스펙 논의
  • 디자인 시안이 나오면 기획과 디자인을 두고 한번 더 검토, API 변경이 필요한 부분이 있으면 팀원들과 논의
  • API 스펙 문서 완료 시 MSW와 같은 mocking 라이브러리를 사용하여 목업 API로 기능 구현
  • API 개발이 완료되면 mocking 걷어내기 (비활성화)
  • 기능이 정상적으로 작동하는 지 확인
  • 완료

    • 다른 분들도 저와 비슷한 과정을 거치실 것이라고 생각합니다. 더 좋은 프로세스로 업무를 하시는 분들도 계시겠지만요!

    4번 과정에서 프론트엔드 개발자는 API spec 문서를 보면서 Data fetching 함수를 작성하게 됩니다.

    메소드, 경로, 헤더, 상황별 응답 등…

    전달받은 API spec 문서를 살펴보는건 설레면서도 꼼꼼히 살펴야지 하는 긴장감을 주는 과정인 것 같습니다.

    저는 실무에서 Swagger와 Notion을, 사이드 프로젝트에서는 Postman Collections과 Swagger를 주로 사용하고 있습니다.

    TypeScript를 사용하면서 API spec에 맞춰서 request payload, response에 대한 타입들을 선언해두는것은 상당히 귀찮은 일이었는데요..!

    quicktype 같은 json to TypeScript를 제공하는 웹사이트를 활용하면서 귀찮음을 조금씩 덜어내던 중이었습니다.

    하지만 여전히 많은 부분의 타입을 직접 작성해야했습니다.

    그런 중에 OpenAPI Spec(OAS) Generator라는 신세계를 맛보게 되었는데요..!

    이 친구는 이런 일들을 해줍니다.

  • API 통신 함수 자동 생성
  • API 요청/응답에 사용되는 데이터의 TS 정의 자동 생성
  • 예시 결과 리턴하는 stub 서버 코드 자동 생성

    • 그 전에 OpenAPI Spec(OAS)가 뭔지 이해하고 넘어갑시다!

    OAS → https://www.openapis.org/

    OAS는 HTTP 기반 API에 대해서 기계, 사람이 모두 이해할 수 있는 문서를 작성하는 규칙을 명명한 것입니다.

    예를 들어, swagger 문서에서 아래 이미지처럼 링크를 누르면 OAS 문서로 연결되며, Text로 구성되어 있는 JSON 혹은 yaml파일이 OAS(Open Api Specification)가 됩니다.

    OAS는 API의 json/yaml 문서이고…

    그러면 OAS Generator는 무엇일까요? → OAS yaml/json 파일로 Source code를 생성해주는 도구입니다.

  • API Swagger → OAS text 파일(.yaml) → Source Code(.ts)로 변환해준다.
  • Geneartor 종류에 따라 다양한 output(Java, Kotlin, typescript, etc.)을 만들 수 있다.

    • 이 것은 어떤 이점들을 가져올까요?

  • 비즈니스 로직이나 뷰 짤 시간 증가
  • 휴먼 에러 감소
  • API 주소 오타 / 타입 정의 (솔직하게 고백하자면 아주 가끔 오타를 낼 때가 있습니다…)

    • 너무 유용하지 않나요! 🤭

    이제 실무에 적용했던 과정을 남겨보겠습니다.

    실전편

    openapi-generator-cli를 전역에 설치하고 버전을 확인해보겠습니다.

    shell
    yarn add @openapitools/openapi-generator-cli -g
openapi-generator-cli version //버전 확인

    oas generator에는 여러 종류가 있는데, 프론트엔드에서는 typescript-axios와 typescript-fetch를 많이 사용합니다.

    저는 CSR환경에서 axios&tanstack-query조합을 사용하고 있어서 typescript-axios를 선택하겠습니다.

    oas(OpenAPI spec)에 따라 파일 생성 (TypeScript)

    shell
    openapi-generator-cli generate -i ./src/json/api-spec.json -g typescript-axios -o ./src/generate

    각 flag들의 의미는 아래와 같습니다.

    -i 입력 파일 경로

    -g 사용할 generator

    -o 생성된 파일이 저장 될 출력 디렉토리

    generate 폴더에 아래와 같은 파일들이 생성됩니다.

  • api.ts: API 엔드포인트를 정의하는 파일입니다. 여러 API 엔드포인트를 포함할 수 있습니다.
  • base.ts: 공통으로 사용되는 기본 클래스와 헬퍼 메서드들이 정의된 파일입니다. 다른 API 클래스들이 이 파일을 기반으로 생성됩니다.
  • common.ts: 공통으로 사용되는 유틸리티 함수와 타입 정의가 포함된 파일입니다.
  • base.ts: 기본 API 클래스와 헬퍼 메서드들이 정의된 파일. 다른 API 클래스들이 이 파일을 기반으로 생성됩니다.
  • configuration.ts: API 클라이언트 설정을 관리하는 파일. 기본 URL, 헤더, 타임아웃 등의 설정을 정의합니다.
  • index.ts: 생성된 모든 파일을 한 곳에서 불러와서 사용할 수 있도록 하는 엔트리 포인트 파일.
  • git_push.sh: 생성된 코드를 Git 저장소에 푸시하기 위한 스크립트 파일입니다. 자동 배포 또는 버전 관리를 위한 스크립트로 사용됩니다.
  • index.ts: 생성된 모든 파일을 한 곳에서 불러와서 사용할 수 있도록 하는 엔트리 포인트 파일입니다.

    • api.ts파일을 확인해보면…

  • OpenAPI 스펙을 기반으로 타입과 인터페이스를 자동 생성해준 것을 볼 수 있습니다.

  • 함수도 자동 생성해준답니다!

    • 이렇게 되면 스펙에 정의된 대로 API를 구현하게 되어 서버/클라이언트 간의 일관성을 보장할 수 있게됩니다.

    또한, API 변경 사항을 스펙에서 관리하여 변경된 내용을 기반으로 자동으로 코드를 재생성할 수 있어 유지보수가 용이하게됩니다.

    다음 번에는 mustache문법을 사용해 템플릿을 만들어 자동 생성되는 코드를 좀 더 사용하기 편리하게 생성해보도록 하겠습니다~