사전작업

자바설치

먼저 java를 설치해줘야한다. (openapi-generator-cli와 swagger codegen은 모두 java로 작성되었기 때문😯. 다른 걱정할필요없이 java가 설치되있기만하면된다.)

Java Oracle Download 공식 사이트 :
https://www.oracle.com/kr/java/technologies/downloads/#java19

본인은 Mac을 사용하고있어, mac을 기준으로 설명하자면 본인의 Mac이 Apple M1칩을 사용하고있다면 Arm64를, Intel칩을 사용하고있다면 x64를 선택해 다운받으면된다. Comp Archive와 DMG는 큰차이없고 본인은 DMG를 이용해 설치하였다.

다운받으면 위와같이 Java(JDK)가 있는것이 보이고 아래와같이 설치를 진행하면된다.

openapi-generator-cli 설치

java설치가 완료되었다면 1단계 준비는 끝이다.

이제 code generator를 선택해 사용하면되는데
Swagger codegen 과 openapi-generator-cli 가 있다.

본인은 좀더 최신이면서 커스텀옵션이 많고, 유저글도 상대적으로 많은 openapi-generator-cli를 사용했다.

아래의 코드를 실행해 cli를 다운받자.

yarn add "@openapitools/openapi-generator-cli"

설치했다면 api 및 type generate시 원하는 결과 언어를 살펴보자.

지원하는 언어 목록은 아래의 링크에서 확인할 수 있다.
https://openapi-generator.tech/docs/generators

본인은 typescript와 axios를 사용하고있어 typescript-axiso를 선택할것이다.

타입 및 API생성 명령어 추가하기

그럼 이제 타입 및 API생성을 위한 명령어를 package.json에 추가하자.

"openapi": "openapi-generator-cli generate -i https://test.steelboso.com/swagger/?format=openapi -g typescript-axios -o ./models --skip-validate-spec",

순서대로 설명하자면
1. openapi-generator-cli로 generate를 시행하겠다.
2. input값으로 참조할 파일 또는 api docs 주소(swagger)

3. 생성할 언어타입 (본인은 typescript-axios)
4. output 경로를 ./models로 설정(없으면 생성된다)
5. input값으로 주는 파일의 validation을 스킵하였다(--skip-validate-spec)
자세한 설명은 아래의 링크를 참고하자.
https://openapi-generator.tech/docs/usage#generate

위의 설정은 openapi-config.yaml에서도 가능하다.

위와같이 설정하면 명령어를 아래와 같이 사용할 수 도 있다.

"openapi": "openapi-generator-cli generate -c ./openapi-config.yaml"

설정한 명령어를 'yarn run openapi'와 같이 실행하면 아래의 결과물을 얻을 수 있다.

아래와 같이 api.ts 파일을 확인해보면 타입이 자동으로 생성된것을 볼 수 있다.

API도 자동으로 생성된것을 볼 수 있다.
(본인은 생성된 API는 그대로 사용하긴 어렵다고 판단되어 기존에 작성했던 api를 사용하고있다)

생각보다 긴여정이지만, REST API와 Typescript를 사용하고있다면 타입자동생성기능 하나만 보더라도 꽤 강력한기능이니, 사용하면 좋을것같다.