openapi-generator (Next/NestJS)

gyojinnK·2024년 5월 9일

TIL - 지나치지 말고 집중해보기

목록 보기

22/23

프론트엔드 개발자를 꿈꾸며 매번 React를 사용하던 내가 특별한 기회을 얻었다.
바로 NextJS와 NestJS를 활용한 웹 애플리케이션 프로젝트이다.
예상하기에 앞으로는 NextJS와 NestJS 관련 글을 많이 작성할 것 같다.
~~프론트만 하다가 백엔드까지 하려니까 처음 개발하는 기분...~~

NestJS openapi-generator

오늘 다뤄볼 주제는 NestJS 자체는 아니다.
아직 공부가 많이 필요하기도 하고 현재 진행하는 프로젝트에 바로 투입해야하기 때문에 진득하게 학습할 시간이 많이 없다...

오늘은 백엔드에서 개발한 API를 프론트엔드에서 쉽게 매핑하여 사용할 수 있도록 지원하는 OpenAPI의 generator에 대해서 소개하고자 한다.

이거 지리는데 왜 안씀?

openapi-generator는 기존 프론트/백 구조의 웹 개발에서의 불편함을 큰 부분 해소해준다.

트렌드세터 Typescript와 함께

요즘 Javascript 기반의 개발이라 하면 디폴트 값으로 Typescript를 이용한다.
Typescript를 활용할 때 openapi-generator를 사용한다면 우리는 퇴근하고 넷플릭스를 더 많은 시간 즐길 수 있다ㅎㅎ

아니 뭘 해주시길래?

openapi-generator는 백엔드와 연동하여 백엔드에 정의되어 있는 모듈들의 타입을 자동으로 참조하여 코드/파일로 프론트엔드로 가져올 수 있다.
이는 프론트엔드 개발 시에 백엔드 메소드의 여러 타입들을 직접 타이핑하지 않아도 되며 백엔드 API 모듈 개발에만 집중할 수 있다.

백엔드에 위와 같은 auth module을 만들고
Swagger를 통해 확인해보면

API 문서가 자동으로 생성된 것을 확인할 수 있다.

우리는 이를 openapi-generator를 이용하여 프론트엔드 개발 파트로 가져오기만 하면 된다.

openapi-generator 설정 in FE

npm package 설치

npm install @openapitools/openapi-generator-cli -g

package.json scripts 설정

 "scripts": {
    ...
    "openapi": "curl YOUR_API_PATH/api-json > .openapi-generator/templates/api.json && openapi-generator-cli generate -g typescript-axios -i .openapi-generator/templates/api.json -o src/lib/openapi"
  },

curl YOUR_API_PATH/api-json > .openapi-generator/templates/api.json
- curl은 명령줄 도구로, URL로부터 데이터를 전송받거나 전송하기 위해 사용된다.
- 이 부분은 YOUR_API_PATH/api-json 주소로부터 데이터를 요청한다.
- > 연산자는 왼쪽에서 오른쪽으로 데이터를 리디렉션한다. 즉, curl을 통해 받은 데이터를 .openapi-generator/templates/api.json 파일에 저장합니다. 여기서 .openapi-generator/templates는 디렉토리 경로이며, api.json 파일에 API 스펙이 저장됩니다.
openapi-generator-cli generate -g typescript-axios -i .openapi-generator/templates/api.json -o src/lib/openapi
- openapi-generator-cli는 OpenAPI Generator의 명령줄 인터페이스이다. 이 도구는 OpenAPI 스펙을 기반으로 클라이언트 라이브러리, 서버 스텁, API 문서 등을 자동으로 생성할 수 있다.
- generate 명령어는 실제 생성 과정을 시작한다.
- -g typescript-axios 옵션은 생성할 코드의 종류를 지정한다. 여기서는 typescript-axios를 사용하여, TypeScript 언어로 작성된 Axios 기반의 HTTP 클라이언트 코드를 생성하겠다는 의미이다.
- -i .openapi-generator/templates/api.json 옵션은 입력 파일을 지정한다. 이전 단계에서 저장된 api.json 파일이 사용된다. 이 파일에는 API의 정의가 담겨 있으며, 생성 과정에서 참조된다.
- -o src/lib/openapi 옵션은 생성된 코드의 출력 디렉토리를 지정합니다. 이 경우, 프로젝트 내 src/lib/openapi 경로에 생성된 코드가 저장된다.
  
  즉, 이 명령어는 로컬 서버에서 OpenAPI 스펙을 받아와서 이를 기반으로 TypeScript와 Axios를 사용하는 클라이언트 코드를 자동으로 생성하고, 이를 프로젝트 내 지정된 위치에 저장하는 과정을 수행한다.