OpenAPI Generator와 Git Subtree를 이용한 프로젝트 관리

dalbodre·2022년 4월 6일

study

목록 보기

5/6

OpenAPI Generator

일반적으로 프론트엔드는 백엔드에서 swagger와 같은 문서 툴로 정의된 API 명세를 전달받게 됩니다. 자바스크립트에서라면 바로 fetch 혹은 axios로 api에 요청하는 코드를 작성하면 되지만, 타입스크립트의 경우 swagger에 명시된 타입을 바탕으로 추가적인 타입을 정의하는 단계가 필요합니다. 하나의 요청/응답에는 한두개부터 수십개까지의 타입 정의가 필요하며, 규모가 커지거나 변경사항이 있을 경우 생산성에 영향이 있을 수 있습니다. OpenAPI Generator는 OpenAPI Specification를 만족하는 API 명세(yaml 또는 json 파일)로부터 요청과 응답에 필요한 타입들과 호출 함수들을 자동으로 생성하여 이러한 문제를 해결할 수 있습니다.

OpenAPI Generator 실행

JDK가 함께 필요하기 때문에 설치되지 않은 경우 설치/환경변수 설정을 먼저 해주어야 합니다.

아래의 npx 명령어를 사용하여 추가적인 설치 없이 OpenAPI Generator을 사용할 수 있습니다.

> npx @openapitools/openapi-generator-cli generate -i <file> -g <generator> -o <directory>

개별적으로 npm, homebrew, scoop, docker를 사용하여 글로벌하게 설치할 수도 있습니다.(참고 : https://openapi-generator.tech/docs/installation)

> npm install @openapitools/openapi-generator-cli -g
> brew install openapi-generator
> scoop install openapi-generator-cli

OpenAPI Generator 실행 옵션

OpenAPI Generator CLI를 실행하는 옵션은 다음과 같습니다.

-i: 포함할 파일 목록 작성
-g: generator 이름
-o: 저장할 디렉토리 이름

OpenAPI Generator가 생성할 수 있는 generator에는 typescript-axios, javascript-fetch, javascript-axios, typescript-fetch 등이 있습니다. 더욱 많은 generator 리스트는 https://openapi-generator.tech/docs/generators/ 에서 확인할 수 있습니다.

Example

OpenAPI INITIATIVE에서는 몇가지 예제 데이터를 제공하고 있는데, 그 중 petstore.yaml 파일과 이를 바탕으로 타입과 호출 함수들을 생성해보겠습니다.

예시 데이터에서 OpenAPI Generator 실행

> cd example
> npx @openapitools/openapi-generator-cli generate \
    -i petstore.json \
    -g typescript-axios \
    -o typescript-axios/

위의 명령어를 실행하면 generated된 코드들을 typescript-axios 폴더에서 확인하실 수 있습니다.

프로젝트 관리: subtree

1. 상위 레포지토리에서 서브트리 원격 저장소 추가

git remote add subtree-test subtree-test.git

상위 레포지토리에서 서브트리를 fetch, pull, push 하기 위해 서브트리로 사용할 현재의 Git 저장소를 상위 저장소의 새로운 원격 저장소로서 추가합니다. 아래에서는 폴더의 이름을 원격 저장소의 이름과 동일하게 cm-api-specification로 지정하였으나, 각 상위 레포지토리에서 다르게 지정할 수 있습니다. 저장소 추가 후에는 git remote 명령어로 옳게 추가되었는지 확인합니다.

2. 상위 레포지토리에서 서브트리 추가

git subtree add --prefix subtree subtree-test master

명령어의 각 요소는 git subtree add --prefix <클론할 폴더> <원격 저장소의 이름> <브랜치 이름> <squash 여부> 순서입니다. --prefix 옵션은 서브트리를 클론할 폴더를 지정하고, 클론될 서브트리 원격 저장소의 이름, 체크아웃할 브랜치 이름을 지정하면 서브트리가 추가됩니다.

서브트리를 추가할 때에 subtree에 존재하던 기존의 모든 커밋을 가져오지 않으려면 squash 옵션을 뒤에 추가하면 됩니다. 단, --squash 옵션을 추가한 경우 이후 git subtree pull 명령어를 실행할 때에도 --squash 옵션을 마지막에 추가해주어야 합니다. 동일 레포지토리로 인식하지 못하고 fatal: refusing to merge unrelated histories 에러가 발생할 수 있습니다.

서브트리가 옳게 추가되면 상위 레포지토리의 폴더 구조는 아래와 같습니다.

상위 레포
├─ README.md (상위 레포지토리의 파일)
└─ subtree-test (서브트리 폴더)
   └─ README.md (서브트리의 파일)

3. 상위 레포지토리에서 서브트리 업데이트

상위 레포지토리에서 서브트리의 변경사항을 내려받고 업데이트하는 명령어는 아래와 같습니다.

> git remote update 또는 git fetch subtree-test master
> git subtree pull --prefix subtree subtree-test master

> git subtree push --prefix subtree subtree-test master

변경사항이 있는 경우 자동으로 머지 커밋이 생성될 수 있으며, 명령어가 짧지 않으므로 각 상위 폴더에서 npm 스크립트 등을 작성하여 사용하는 편이 좋습니다.