Open API Generator 도입 후기

웹 프로젝트 Open API Generator를 도입기

프로젝트에 Open API Generator를 도입하면서 경험한 내용들을 작성해보았다.

Open API Generator 용도

작성일 기준(2022.03.22 21)으로 프로젝트에 적용한 기능들은 크게 두가지이다.

1. API 함수들 자동 생성
2. API 요청 / 응답 타입 자동 생성 (DTO)

참조: 공식 문서

Open API Generator 도입 장점

Open API Generator 도입 후 직접 체감한 장점들은 아래와 같았다.

1. 타입 작성 오류가 줄어듬

   • 객체 안에 객체 안에 객체 타입을 작성하다가 스스로 무한루프에 빠지게 되는 상황이 줄어듬

   • Enum으로 선언된 타입(ex User.status)에 변동이 생겨도 추가적인 타입 수정없이 바로 기능적인 부분만 수정하면 됨

2. 휴먼 에러 감소

   • API 호출시 parmeter, data를 잘못 넣어서 호출한 후에 리포팅 횟수 줄어듬

3. 작업 소요 시간 줄어듬

   • 개발 시간중 타입 작성 시간만 4할정도 할애하였으나 이 부분을 자동으로 생성해주므로 전체적인 개발 시간 감소됨

   • API 업데이트 후 명령어 한줄만 입력하면 수정된 내용이 전체 반영되어 작업까지 반영이 빨라짐

프로젝트 작업시 데이터를 어떻게 넘겨줄 것인지 로직적으로 집중할 수 있었으며, API 수정에 대하여 스트레스 감소 및 수정된 API가 프로젝트에 반영되기까지의 시간이 매우 단축었다.

같은 프로젝트를 진행한다고 하였을때 기존 작업량과 비교해 보았다.

Antd를 사용한 관리자 프로젝트를 만든다고 하였을때, 기존에는 단순한 CRUD 만드는데 1시간이 걸렸다면, Open API Generator 도입 후에는 작업 시간이 절반정도 절감할 수 있었다.

이를 통하여 절감된 시간을 프로젝트에 대하여 조금 더 이해하기 위하여 시간을 사용할 수 있었고 결과적으로 프로젝트 완성도가 더욱 더 올라가는 효과를 추가로 발생하였다.

Open API Generator 단점

먼저 Open API 도입하면서 느꼈던 부분은 다음과 같았다.

• 환경에 따라 웹이 무거워질 수도 있다.

• 충분히 이해될만큼의 참조할 수 있는 리소스가 매우 적다.

• API 스웨거의 스키마에는 기재되어있지만 타입(ex GetAuthResDto) 선언이 되어있지 않거나, 타입 선언이 올바르지 않은 경우(ex. 실질적인 데이터는 string이지만, 선언한 타입은 number인 경우 타입을 새로 작성해주어야하는 번거로움이 있었다.
  

• 백엔드 개발 환경에 따라 어떤식으로 사용해야할지 감이 안잡히는 경우도 발생했다.

  ex) defaultApi의 정의는 무엇인지? faqApi의 정의는 무엇인지 추가적으로 논의가 필요했다.

  • 로그인 - defaultApi.authControllerPostAuth()
  • 공지사항 조회 - defaultApi.noticesControllerFindAll()
  • FAQ 리스트 조회 - faqApi.faqsControllerFindAll()

Open API Generator 도입 후기 요약

먼저 관리자에서 도입했을때는 메뉴 단위로 개발을 진행하여 타입을 공유하는 범위가 적어 프로젝트 개발 속도가 조금 빨라졌었지만, 일반 서비스 웹 페이지를 개발했을때는 타입을 공유하는 범위가 조금 더 넓어져서 효과적으로 사용할 수 있었다.
신규 서비스에 대하여 작업을 많이 진행했었는데, 신규 서비스 특성상 기획이 자구 바뀌는 경우가 많았다. 백엔드와 동시에 진행하는 경우도 자주 발생하였는데 이때 스크립트 명령어 하나만으로 백엔드가 변경된 부분이 한번에 작성되어 편리하게 사용할 수 있었다.

Open API Generator 설정 방법

shell 스크립트를 작성하여 npm 스크립트로 실행하도록 설정하였다.

genrate-api.sh

#!/bin/bash
API_URL=API 주소의 경로를 입력
TARGET_PATH=API 함수들을 모아놓을 경로 입력

if ! find $TARGET_PATH; then
  echo "디렉토리 생성중... $TARGET_PATH "
  mkdir $TARGET_PATH
  echo "디렉토리 생성 완료"
fi

echo "인터페이스 생성중... $TARGET_PATH "
npx @openapitools/openapi-generator-cli generate -i $API_URL -g typescript-axios -o $TARGET_PATH --skip-validate-spec --additional-properties useSingleRequestParameter

package.json > script

api-genrate: sh 파일경로/generate-api.sh

Hello from OpenAPI Generator | OpenAPI Generator