서론
약 1년전, 이직을 위한 면접을 보러 다니던 시기였다.
TS를 찍먹만 해보던 시절, 면접 질문에 TS 관련한 내용이 나오면 잘 모르겠다는 답변만 내놓던 시절이 있었다.
그 중 백엔드 API의 Response는 타입 처리를 어떻게 하시나요? 라는 질문에 아는 방법이 없어서 any 처리를 해봤다 라는 답변뿐이 할 수 없었다.(면접은 당연하게도 떨어졌다)
만약 어떤 방법을 써야할지 모르겠다면 이글을 가볍게 읽어 보기 바란다.
(1년이 지나서야 쓰는 API response 에 type 적용하기)
API의 Response는 타입 처리를 어떻게 하시나요?
결론 부터 말하자면,
Swagger의 OPEN API의 명세를 이용해 interface를 자동 생성 하는 방법을 사용한다
swagger, open API란 ?
Swagger 는 REST API를 설계, 빌드, 문서화 및 사용하는 데 도움이되는 OpenAPI 사양을 중심으로 구축 된 오픈 소스 도구 세트입니다.
(swagger에 대한 자세한 내용은 다른 글을 읽는 것을 추천한다.)
Swagger는 백엔드 API를 쉽게 문서화 해줄 수 있다.
현업에서 REST API(request, response 및 error code등 ) 프론트엔드와 백엔드가 소통을 이 Swagger를 이용해서 할 수 있다.
Swagger Page는 backend개발자가 프로젝트 환경 세팅 후, Swagger 페이지를 자동으로 만들어주는 작업을 진행하게 되고, 위와 같은 Swagger Page 가 생기게 된다.
위와 같은 Swagger Page는 Page를 만들어주기 위해 어떠한 양식을 따라, 작성되게 되는데 이를 OPEN API 라고 한다.
Open API 명세는 위와 같은 JSON 형식 또는 yml 형식으로 작성 될 수 있고,
상세한 명세는 다음 링크에서 확인할 수 있다.
모든 Swagger 페이지에는 이 OPEN API형식의 명세 문서를 기반으로 동작하고, 각각의 API 에 대한 정보를 알 수 있다.
이 OPEN API 정보를 이용해 Front 개발자는 type interface 를 자동으로 생성해주는 parser를 이용할 수 있다.
- NPM swagger-typescript-api
- NPM openapi-typescript
- Swagger-codegen
- OpenAPI Generator
위와 같은 라이브러리를 이용하면 OPEN API 형식의 JSON 파일을 통해 손쉽게 typescript의 interface를 만들어 줄 수 있다.
결론 & 주의 사항
- 위의 라이브러리를 이용한다면 Type-safe 한 개발을 할 수 있다.
- 프론트 개발자의 시간을 절약할 수 있다.
다만,
swagger의 명세 정보가 잘못 되어 만들어진 경우 backend와 소통을 통해 swagger type 을 적절히 수정해주는 작업이 필요하다.
swagger를 사용하고 있지 않는 프로젝트라면 swagger를 도입 여부를 생각해보는 것이 좋을거 같다.
