[typescript 환경 구축] OpenAPI Generator와 함께 타입스크립트를 편리하게 사용해보자

openapi-generator란

• RESTful API를 보다 쉽고 편리하게, 일관되게 설계하고 개발할 수 있도록 자동화 도구를 제공하는 오픈소스
• 간단히 설명하면 배포된 swagger 문서를 기반으로 클라이언트에서 바로 사용가능한 type을 자동으로 생성해줌

 

swagger에 나와있는 각 api들의 type을 이렇게 한 번에 다운받을 수 있다

 

 

 

필요성

[POST] token/issue라는 API가 있다고 하자.

// request

{
  "tokenType": "string",
  "network": "string",
  "tokenName": "string",
  "tokenDecimals": "number",
  "initialSupply": "string",
  "maxSupply": "string",
  "symbolImage": "string",
  "walletAddr": "string",
  "officialSite": "string"
}

 

// response

{
  "rows": [
    {
      "id": "number",
      "tokenName": "string",
      "tokenType": "string",
      "network": "string",
      "decimals": "number",
      "initialSupply": "string",
      "maxSupply": "string",
      "symbolImage": "string",
      "quantity": "number",
      "dateOfPbl": "string",
      "situation": "string",
      "contractAddress": "string",
      "space": "string",
      "officialSite": "string",
      "note": "string"
    }
  ],
...
}

 

 

• 위와 같이 request와 response의 항목도 많고, 변수명이 길다보니 프론트엔드 개발자가 swagger를 보고 한땀한땀 입력하다보면 오타가 발생할 확률이 높아 보임
• 또한 back-end에서 변수명이나 type을 임의로 바꾼 뒤, 구두로 전달하지 않는 이상 front-end는 그 사실을 알 수 없기 때문에 에러 발생

• 만약 백엔드 개발자가 '어, 대소문자 오타났네?'라며 변수명을 바꾸거나,
• 원래 string이었던 id값을 number로 바꾸거나,
• array, object 등 데이터구조를 변경해버리면 프론트엔드는 영문도 모른 채 에러를 마주하게 됨

 

 

 

개발환경에 적용하기

프론트엔드에서 openapi 사용을 위해 백엔드에서 따로 해줄 작업은 없다.

 

 

1. npm 설치 (링크)

pnpm i @openapitools/openapi-generator-cli --save -D

 

 

 

2. 프로젝트 root 폴더에 openapi.json 파일 생성

 

// openapi.json

{
  "modelPackage": "src/model",
  "apiPackage": "api",
  "withSeparateModelsAndApi": true
}


// (참고) openapitools.json

{
  "$schema": "node_modules/@openapitools/openapi-generator-cli/config.schema.json",
  "spaces": 2,
  "generator-cli": {
    "version": "4.3.1"
  }
}

 

 

3. package.json 파일의 스크립트 수정

 

"openapi:develop": "rm -rf ./models && rm -rf ./src/model && openapi-generator-cli generate -i http://159.138.247.188:8080/docs-json -g typescript-axios -o ./models -c ./openapi.json --skip-validate-spec && cp -r -f models/src/model src && rm -rf ./models"

 

 

 

 

이제 pnpm run openapi:develop 명령어를 실행하면 자동으로 swagger에 나와있는 type들을 다운받을 수 있다.

명령어를 나누어 설명해보면,

 

• rm -rf ./models && rm -rf ./src/model : 이전에 다운받았던 type들, 새로 받아질 폴더를 한번 싹 지워줌 (혹시나 덮어씌워지며 꼬이는 일 방지)
• openapi-generator-cli generate : 생성하라
• -i http://xxx.xxx.xxx.xxx:8080/docs-json : 위 주소에 있는 api 목록을 가져와라
  • -i 옵션은 포함할 파일 목록 작성을 의미(타겟 파일 위치 지정)
  • ip주소는 스웨거가 배포된 주소이고, 그 뒤에 붙는 단어는 환경에 따라 달라질 수 있다(검색하면 /docs-json 대신 /openapi.json 이 붙은 스크립트가 많이 나오는데… 주소창에 입력했을 때 아래와 같은 화면이 나오는 주소여야 한다. 우리 프로젝트 경우에는 http://xxx.xxx.xxx.xxx/docs-json 이었음)

 

• -g typescript-axios : -g 옵션은 ‘어떤 제너레이터를 사용할 것인가(생성할 언어타입)’ -목록은 링크 참고
• -o ./models : -o 옵션은 생성될 파일 위치 경로(models 폴더에 만들어라)
• -c ./openapi.json : -c 옵션은 제너레이터 설정파일 (openapi.json 파일을 참조해라)
• --skip-validate-spec : i 옵션으로 준 파일의 validation은 스킵
• cp -r -f models/src/model src : 위에서 만든 models 폴더 안에있는 /src/model 폴더를 복사한 뒤, src 폴더에 붙여넣기 해라 (나는 생성된 type들을 최상위폴더가 아닌 src폴더 안에서 사용하고 싶기 때문에 이 작업을 추가했음)
• rm -rf ./models : 위에서 복사완료했으니, 처음에 만들어진 models 폴더는 지워줌

 

 

 

사용법

터미널에 pnpm run openapi:develop 를 입력해주면 아래와 같이 자동으로 dto 파일들이 생성된다.

 

 

이렇게 import 해서 써주면~ tadah~~ 편리한 타입스크립트 환경 구축 완료,,

 

 

 

 

유의사항

 

종종 백엔드에 실제로 구현되어있는 것과 swagger에 명시되어있는 type이 다른 경우가 있다.

이럴 땐 스웨거에 나와있는 type을 다운받아도 프론트에서 사용할 수가 없으니 백엔드 개발자와 이야기해서 제대로 맞춰줘야 한다.

 

근데 이건 뭐 openapi generator를 사용하기 때문에 맞춰야하는 부가작업이 아니라, 당연히 그렇게 보여야하는 거니...

 

백엔드에서 정의한 dto 이름이 같으면 그런 이슈가 발생할 수 있다고 하니(caching 문제인듯 함), dto name은 유니크하게 사용해야 할 것 같다.