Swagger 타입 자동 생성기 적용기(feat. swagger-typescript-api)

Wonwon·2023년 3월 21일

Swagger swagger-typescript-api 타입자동생성기

Swagger

목록 보기

1/2

Swagger 문서를 이용한 자동 타입 생성기
본 글은 Typescript와 axios환경에 swagger-tyescript-api를 적용한 글입니다.

목표

Swagger 문서(Swagger Docs, Swagger UI)를 이용한 타입 자동 생성기 구현
Request, Response, Error Type까지 전부 생성되야함
위의 2목표를 달성하여 Type-Safe 하게 개발하기

결과물부터 보여주자면 아래와같이 모든 Type이 생성된것을 볼 수 있다.

Request Type = AuthPostLoginPayload
Response Type = AuthPostLoginData
Error Type = AuthPostLoginError

본인은 swagger-typescript-api를 사용하였다. Swagger-codegen, OpenAPI Generator도 있는데 왜? 라고 할 수 있다. 해당 2개의 라이브러리는 범용성도 좋고 널리쓰이긴하나, swagger-typescript-api처럼 생성시 type만을 분리하여 생성하거나, 사람이 보기편하게 type, api를 생성해주진 않았다.

(2가지다 먼저 사용해보았으나 type만 생성하고싶은데 api가 4가지방식으로 생성되거나 type파일만 분리되어 생성되지 않고, api와 type을 한파일에 생성하는 등 문제가 많았다... 물론 필자가 문서에서 적절한 방법을 못찾아서 그럴 수 도 있으나 다른 사람들도 해당 부분이 불편하여 swagger-typescript-api를 만들고 꽤 많은 유저가 있는것이 아닐까...?😂)

설치

아래의 커맨드로 swagger-typescript-api를 설치하자.

npm i swagger-typescript-api
또는
yarn add swagger-typescript-api

실행 커맨드 작성

package.json에 실행 커맨드를 추가하자.

"swagger-typescript-api": "swagger-typescript-api -p {Swagger 문서 Path!} -r -o {생성 결과로 지정할 경로} --modular -d --extract-request-body --extract-response-body --extract-response-error --axios",

명령어를 하나하나 살펴보면 아래와같다.

-p {Swagger 문서 Path!} : 정보를 가져올 path를 지정해주는 옵션이다.
-p https://test.service.com/swagger/?format=openapi 처럼 url을 지정해주거나,
-p ./swaggerDoc.json 처럼 local 파일 path를 지정해줄 수 도 있다.

아래의 사진의 가려진부분이 path로 사용될 swagger docs url이다.

실제로 해당 url을 가보면 아래와같이 json형식으로된 swagger docs파일을 확인할 수 있다.(이를 이용해 data를 받아와 type을 생성하는것이다)

-r : request reponse 에 대한 더 자세한 정보를 생성하겠다는 옵션이다.
-o {생성 결과로 지정할 경로} : Output 경로를 지정하는 옵션이다.
-o ./models 로 사용하면 결과물이 models폴더에 생성된다.
-d : 기본 response 값을 success시의 response값으로 지정하겠다는 뜻이다.(swagger 문서상 아닌경우가 있다고?한다)
--extract-request-body --extract-response-body --extract-response-error : reqeust, response, error Type을 생성하는 옵션이다.
--aixos : API생성시 axios함수로 생성하게하는 옵션이다.

위의 예시를 토대로 완성한 실행 커맨드는 아래와 같다.

"swagger-typescript-api": "swagger-typescript-api -p https://test.swaggerdocs.com/swagger/?format=openapi -r -o ./models --modular -d --extract-request-body --extract-response-body --extract-response-error --axios"