학습 이유

react에서 프로젝트를 진행하면서 js -> ts 로 마이그레이션 하면서 백엔드에서 정의한 타입들을 일일이 작성하는 것이 아닌 라이브러리를 사용하여 한번에 타입들을 생성할 수 있다는 것을 알고 적용해보고 싶어짐
위의기능을 제공하는 라이브러리들 중 swagger-typescript-api가 맞을 것 같아 해당 라이브러리를 학습

학습 목표

swagger-typescript-api의 공식 문서를 학습 및 프로젝트에 적용

적용 방식

swagger-typescript-api github

사용기

package.json

package.json의 scripts 내부에 다음과 같이 실행 명령어를 등록
1. generate-api.ts는 따로 정의할 수 있는 설정 파일
2. yarn run swagger를 통해 src/apis/generated에 스웨거에서 타입들을 정의한 파일을 자동으로 생성함(data-contracts.ts 및 백엔드에서 정의한 controller별로 파일이 생김)

scripts: {
  "swagger": "rimraf ./src/apis/generated && tsc --esModuleInterop ./generate-api.ts && node ./generate-api.js && rimraf ./generate-api.js",
}

generate-api.ts

generate-api.ts 파일에서 생성 조건들을 정의할 수 있음

import path from 'path'
import { generateApi } from 'swagger-typescript=api';

generateApi({
  name: 'swaggerGenerate.ts', //생성할 파일 이름을 지정
  url: 'http://localhost:8002/v3/api-docs', //swagger 문서 주소
  input: path.resolve(process.cwd(), './swagger.json'), //로컬 swagger json 파일의 경로를 지정, url과 함꼐 사용하지 않음, 해당 프로젝트에서는 url을 사용
  output: path.resolve(process.cwd(), './src/apis/generated'), //생성된 api 클라이언트 파일을 저장할 디렉토리 경로
  templates: path.resolve(process.cwd(), './src/apis/templates'), //커스텀 템플릿 파일들이 저장된 디렉토리의 경로를 지정
  httpClientType: 'axios', //생성된 클라이언트 코드에서 사용할 http 클라이언트 라이브러리를 지정, 이에 따라 src/generated/apis 내부에 http-client 파일이 생성되는 듯 함
  generateClient: true, //api 클라이언트를 생성할지 여부, false인 경우 http-client파일이 안생기는 듯
  toJS: false, //생성된 파일의 타입을 js로 나타낼지 여부, false인 경우 ts로 저장됨
  generateResponses: true, //http 응답 타입을 생성할지 여부
  typeSuffix: 'Dto', //생성된 타입 이름에 추가할 접미사
  modular: true, //모듈 단위로 코드를 생성할지 여부, 각각의 서비스나 컨트롤러를 개별 파일로 생성
  extractEnums: true, //swagger 문서의 enum 타입을 추출할지 여부
  singleHttpClient: true, //단일 http 클라이언트를 사용할지 여부
  extractRequestParams: true, //요청 파라미터를 별도의 타입으로 추출할지 여부
  extractRequestBody: true, //요청 body를 별도의 타입으로 추출할지 여부
  extractResponseBody: true, //응답 body를 별도의 타입으로 추출할지 여부
  extractResponseError: true, //응답 에러를 별도의 타입으로 추출할지 여부
  unwrapResponseData: true, //응답 데이터에서 'data' 속성만 추출할지 여부
  sortTypes: true, // 생성된 타입들을 알파벳 순서로 정렬할지 여부
  ...
}

외에도 prettier 속성을 정의하여 생성된 파일의 형식도 지정이 가능하며 type이름을 변환하거나 중복되는 타입들을 제거할 수 있음