OpenApi-Generator

OpenApi-Generator란?

yaml, json로된 api명세파일을 자동으로 코드로 자동 변환시켜주는 라이브러리

 

사용 이유

현재 프론트엔드 작업 시 api를 사용하기 위해 만들어진 Swagger UI를 보고 타입과 api를 직접 타이핑 해서 적용.

직접 입력하기 때문에 실수 가능성과 번거로움이 생기고, 만약 api 수정 시 변경 내용을 따라가서 수정해야함.

만약 OpenApi-Generator 사용시 이러한 번거로움과 실수를 방지하고 개발시간을 단축시켜 줄 수 있음.

 

사용 방법

1. install

- 해당 프로젝트 root에서 yarn add @openapitools/openapi-generator-cli --dev

2. OpenApi 명세가 정의된 Json / Yaml 파일 준비

- Swagger의 경우 아래와 같이 Network Tab에서 해당 Json 객체를 가져올 수 있음

3. 실행 

- yarn openapi-generator-cli generate -i [명세파일] -g [변활할 형식] -o [변환된 파일 저장 경로] -c [설정파일 경로]

• -i 옵션의 경우 해당 명세파일의 경로를 정의함. json / yaml 파일을 반환하는 url 주소도 가능
• -g 옵션의 경우 변환할 형식을 정의함. 현재 프로젝트의 경우 typescript와 api의 경우 axios를 사용하므로 typescript-axios 사용https://openapi-generator.tech/docs/generators(여러 형식으로 변환가능함)
• -c 옵션의 경우 코드 생성 시 여러 옵션을 정의한 파일의 경로를 지정. https://openapi-generator.tech/docs/generators/typescript-axios/ (코드 생성 시의 옵션을 통일하여 사용 가능)
• -o 옵션의 경우 자동생성 될 코드파일이 저장될 경로. 해당 경로를 root로 -c 에서 정의한 옵션을 통해 api파일과 타입 파일을 나눠서 저장 할 수 있음.
• ex -> yarn openapi-generator-cli generate -i ./petstore.json -g typescript-axios -o ./src/model

4. 변환될 코드 형식 수정

- 실제로 Swagger의 json파일을 OpenApi-Generator로 변환했을 때의 코드는 이렇다.

(yarn openapi-generator-cli generate -i petstore.json -g typescript-axios -o ./src/openapi -c openapi.json)

 

 

 

 

 

 

 

 

 

 

 

 

 

 

openapi 폴더안에 generator를 통해 변환된 여러 설정파일이 들어있고, 설정파일을 통해 api와 타입 폴더를 나눠서 구성하였음.

변환된 타입 코드

 

변환된 api 코드

타입의 경우 비교적 심플하지만, axios로 변환된 api의 경우 내부에 생성된 여러 유틸파일들이 얽혀 있는걸 볼 수 있다. 

해당 api를 단순 사용만 하면 상관 없겠지만 만약 해당 포맷을 커스텀하거나 코드 수정이 필요하다면 어느정도의 러닝커브가 필요하다. (공통 Axios 설정이 적용되는건 확인 되었음)

 

- 형식 변경 방법(대략적)

• yarn openapi-generator-cli author template  -o [mustaches 파일이 저장될 경로] -g typescript-axios 커맨드 실행 시 해당 경로에 mustaches 템플릿 파일이 저장된다. 해당 템플릿 파일을 수정하면 generate되는 코드의 형식을 변경 할 수있다. 

5. 사용시 유의점

- enum 타입의 경우 만약 한글 사용시 아래와 같은 에러가 나기 때문에, 해당 에러코드를 직접 수정해 줘야 한다.

- 해당 타입에 대한 초기화 변수들은 직접 추가를 해줘야 한다.

 

6. 사용 후 느낀점

- 타입을 자동으로 생성하는 기능은 개발시간 단축과 정확도를 향상 시키는 유용한 기능이다. 하지만 api 사용은 기존의 인증과 같은 공통 axios 설정에 영향을 미치지 않는지 추가적인 테스트가 필요할것 같다.