[Swagger Codegen] swagger-typescript-api

백엔드와 프론트엔드 협업 시에 백엔드 API 제작이 완료되면 보통 REST API의 경우 swagger를 통해 API Docs를 작성하게 되는데 이 때에 백엔드에서 작성된 API 타입을 그대로 가져와 프론트 API 통신 코드 작성 시 타입을 지정해 줄 수 있는 도구입니다.

https://www.npmjs.com/package/swagger-typescript-api

// package.json
{
...
  "scripts": {
    ...
    "generate": "npx swagger-typescript-api -p http://petstore.swagger.io/v2/swagger.json -o ./src/common/interfaces -n types.d.ts "
  },
}

스크립트에 해당 코드를 작성하고 npm run generate 명령어를 작성하면 타입이 작성됩니다.

-p 옵션은 우리가 변환할 swagger.json의 경로
-o는 출력할 폴더의 경로
-n은 출력할 파일의 이름을 지정합니다.

이 명령어는 처음 생성할 때에도 실행해줘야 하지만 만약 백엔드 api에 수정이 발생한다면 최신의 docs 타입을 가져와 적용시켜 줄 수 있도록 프론트에서도 명령어를 실행해줘야 합니다.

 

해당 명령어를 실행하면 아래와 같이 변환이 완료되었다는 안내가 생성되고 해당 경로를 확인해보면

 

 

이렇게 src/common/interfaces 폴더 안에 types.d.ts 파일이 생성되었습니다.
(명령어에서는 경로가 src/interfaces 로 되어 있으나 오타입니다. 단순히 내가 지정할 경로이므로 내가 만들어주고 싶은 경로로 작성하시면 됩니다.)

완성된 아래의 타입을 그대로 import 해서 작성해주시면 됩니다.

// src/common/config/axios/logout.ts
import { RequestParams } from '@/common/interfaces/types';

export const logoutUser = (params: RequestParams) => {
  return request('get', '/user/logout', params)
}

swagger-codgen을 사용한다고 해서 모든 타입이 완벽하게 추출되는 것은 아니지만 모든 타입을 다시 작성해줘야한다는 번거로움이 조금 줄어듭니다. 잘 사용하시면 프론트엔드와 백엔드의 커뮤니케이션도 줄일 수 있으며 생산성을 증가시킬 수 있습니다.