편리한 API 제너레이터 ‘swagger-typescript-api’

zwoo

9분

2023.12.28.

11.1K

몇

년차,

어떤 스킬

어떤 직무

의

독자들이 봤을까요?

어떤 독자들이 봤는지 궁금하다면?

로그인

스웨거(Swagger)의 탄생

생각보다 개발자도 문서 작업이 필요할 때가 많다. 그래서 문서화해야 할 때 더 효율적이고 자동화된 방식을 찾는데, 이때 대표적인 문서로 API 문서가 있다. API 문서는 클라이언트가 백엔드 애플리케이션에 요청을 전송하기 위해 알아야 하는 요청 정보, URL/URI 등을 정리해 둔 약속 문서이기 때문에 반드시 필요하다. API 문서를 작성하는 시간은 API 개수가 많아질수록 늘어나며, 대체로 한 번에 완성하지 못한다. 개발 과정에서 API 함수 시그니처가 변경될 때마다 문서를 업데이트해야 하기 때문인데, 개발자에겐 중요하면서도 번거로운 작업이다.

개발자가 겪는 이러한 어려움을 해결하기 위해 스웨거(Swagger)가 탄생했다. 스웨거는 JSON과 YAML 포맷의 문서를 기반으로 클라이언트에서 사용할 수 있는 RESTful API 파일을 자동으로 생성해 주는 프레임워크다. 2011년 첫 번째 버전을 시작으로 오픈소스 생태계에서 무럭무럭 성장했다. 오픈소스 기여자들은 관리 편의성을 위해 OpenAPI Specification(OAS)이라는 규칙을 정했고, 이것을 스웨거 툴이 지원해야 하는 기능 명세로 삼았다. 이후 이 표준은 API 설계 및 문서화를 위한 표준 스펙으로 자리 잡았고, 많은 툴에서 이 표준을 따르게 되었다.

스웨거가 널리 쓰이면서 API 문서를 전달하고 소통하는 비용과 휴먼에러 가능성이 혁신적으로 줄어들었고, 개발자들은 기능 구현에 집중할 수 있게 되었다. 또한 스웨거에서 제공하는 기능 덕분에 API 테스트 환경도 쉽게 구축할 수 있다.

나는 스웨거에 대해 알고 있었지만, 개발자가 된 이후 지금까지 실제로 사용한 적은 없었다. 수동으로 문서를 주고받곤 했다. 그러던 중 최근 회사 프로젝트에서 API 제너레이터를 사용해 보기로 했고, JSON 파일을 타입스크립트 파일로 변환해 주는 효율적인 라이브러리가 있는지 찾아보게 되었다. 결과적으로 내가 선택한 라이브러리는 ‘swagger-typescript-api’다. API 자동 생성을 처음 해보는 개발자, 특히 나처럼 타입스크립트를 다루는 개발자에게 도움이 되는 라이브러리로 이번 글에서 살펴보고자 한다.

API 자동 생성을 위해 필요한 것들

1) 적합한 라이브러리 찾기

이미 수많은 API 제너레이터 라이브러리가 있지만 저마다 지원하는 옵션은 조금씩 다르다. 그래서 잘 살펴보고 본인에게 적합한 것을 선택해야 한다. 이때 몇 가지 기준을 정해두는 것이 좋다.

첫 번째 기준은 사용자 수다. 사용자 수는 깃허브 start 또는 npm 위클리 다운로드 횟수로 추측할 수 있다. 사용자가 많다는 것은 그만큼 사용성이 높다는 의미로 해석할 수 있다. 만약 기능이 부족하거나 버그가 많고, 제대로 관리되지 않는다면 사용자들은 떠나기 마련이다. 좀 더 안전하게 확인하기 위해서는 업데이트 주기까지 확인하는 것이 좋다.

만약 위클리 다운로드 횟수가 꽤 많아도 마지막 업데이트가 몇 년 전이라면, 제대로 관리되지 않는 상태일 수도 있다. 이 경우 라이브러리를 사용하는 도중 버그가 발생했을 때 패치가 되지 않을 수 있다. 이럴 땐 직접 라이브러리를 고쳐 쓰거나, 새로운 라이브러리를 다시 찾아야 하므로 번거로워진다. 그런데 내가 선택한 swagger-typescript-api는 여러 후보 중 위클리 다운로드 횟수가 가장 높진 않았다. 그러나 10만 회 이상으로 절대적인 수치가 꽤 높다고 판단해 후보에서 제외하지 않았다.

두 번째 기준은 제공되는 옵션을 활용해 사용하고 있는 언어의 장점을 잘 살릴 수 있는지다. 내 경우 타입스크립트를 사용하는 입장에서, 제너레이터가 타입을 잘 추출해주는지가 무엇보다 중요했다. 서버에서 정의해준 Request body, Response body, enum, Error 타입 등을 제너레이터가 잘 추출해 주고, 그렇게 생성된 파일을 클라이언트에서 쉽게 사용할 수 있길 원했다. 재가공할 필요 없이 명령어 하나에 바로 호출해서 쓸 수 있는 api.ts 파일이 생성되는 것 말이다.

2) 적합한 옵션 찾기

이렇게 나름의 기준을 가지고 많은 라이브러리를 살펴보았지만, 명시적 타입 추출을 위한 옵션을 찾기 어려웠다. 많은 OAS 라이브러리 스펙 명세서를 살펴보니, 타입스크립트에 관한 스펙을 비교적 최근에 추가한 것을 알 수 있었다. 타입스크립트는 다른 개발 언어에 비해 역사가 짧은 편이니 그리 이상한 일은 아니다. 하지만 그로 인해 유용한 옵션이 적다는 점이 아쉬웠다. 그래서 타입스크립트에 최적화된 라이브러리를 찾는 데 많은 시간을 들여야 했다.

또 한 가지 어려웠던 점은 복잡성이었다. 대부분 라이브러리에서 제공하는 아웃풋 형태가 예상보다 복잡했다. 그래서 자동으로 생성된 파일들을 바로 사용하기는 어려웠고, 다시 하나의 파일로 재가공하는 과정이 필요했다. 본래 내가 원했던 것은 제너레이터가 api.ts 파일까지 알아서 만들어주는 것이었기 때문에 그 옵션을 찾으려고 노력했다.

3) 필요한 옵션 사용해 generate 하기

위 기준을 통해 라이브러리를 선별한 후, 원하는 기능을 나열해 보았다. 우선 앞서 말한 타입 추출 옵션, 그리고 단순히 API 메서드들만 정의되는 것이 아니라, 가능하다면 API 호출을 수행할 HTTP 클라이언트 인스턴스도 자동 생성되면 편리할 것 같다고 생각했다. 그리고fetch API 대신Axios를 사용할 예정이었기에, Axios 인스턴스와의 호환성도 좋아야 했다.

바로 이 지점에서 최종적으로 swagger-typescript-api를 선택하게 되었다. 타입스크립트에 최적화되어있는 이 제너레이터는 내가 원하는 기능을 모두 갖추고 있었다. 제공되는 옵션을 조합해서 작성한 제너레이팅 스크립트는 다음과 같다.

// api generator using swagger-typescript-api

import { exec } from 'shelljs';
const swaggerPath = `${__dirname}/../packages/api/swagger.json`;
const targetPath = `${__dirname}/../packages/front/src/api`;

async function generateApi() {
    exec(`npx swagger-typescript-api \
    -p ${swaggerPath} \                   // json 또는 yaml 파일 
    -o ${targetPath} \                    // api 파일을 만들 목적지 디렉토리
    -n api.ts \                           // 파일 이름  
    -r \                                  // 요청과 응답에 대한 메타정보를 자세하게 생성 
    --axios \                             // 내장된 axios 클라이언트 인스턴스 사용
    --extract-request-params \              
    --extract-request-body \
    --extract-response-body \
    --extract-response-error \
    --extract-enums \                      // 타입 추출
    --unwrap-response-data                 // response 객체에서 data 객체를 꺼내어 해줌
    `)
}

generateApi()

swagger-typescript-api가 편리한 이유

우선 swagger-typescript-api는 라이브러리는 매우 친절하다. 사용할 수 있는 옵션과 그에 대한 설명, 사용 예시까지 자세하게 안내하고 있다. 여러 언어가 아닌 타입스크립트만을 위한 라이브러리로, 사용자 니즈를 잘 반영한 것 같다. 명시적인 타입 추출이 매우 잘될 뿐만 아니라, 인풋이 되는 json,YAML 파일에 정의되어 있는 타입들을 API 제너레이팅 시점에 원하는 타입으로, 직접 정의해 새로 매핑할 수 있는 기능도 있다. 확장성 면에서 만족스럽고, 이 기능 역시 설명 및 예시가 자세하다.

게다가 Axios와의 호환성도 매우 좋다. Axios 옵션을 이용한 경우 Axios 클래스를 상속받은 HTTP 클라이언트가 만들어지며, 사용자 관점에서 Axios 인스턴스를 생성하는 것과 별반 다르지 않게 쓸 수 있다. 개인적으로 Axios가 익숙해서 선호하는 측면도 있어 큰 장점이라고 생각했다. 그러나 관점에 따라 필수적인 기능이라고 보긴 어렵다.

가령 openapi-typescript는 자체적인 HTTP 클라이언트를 제공하며 인터페이스도 매우 직관적이다. API를 호출할 때 꼭 Fetch API나 Axios 클라이언트를 고집할 이유는 없으므로, 라이브러리에서 자체적으로 제공하는 클라이언트를 사용하는 것도 나쁘지 않을 것이다.

swagger-typescript-api 라이브러리를 통해 만들어지는 결과물은 매우 단순하고 직관적이다. 사실상 단 하나의 파일이 만들어진다. 개인적으로 마음에 들었던 부분인데, 규모가 작은 프로젝트에서 API 정의를 위해 많은 양의 파일을 만들고 싶지 않았기 때문이다. 하지만 이 부분도 사람마다 견해 차이가 있을 것 같다. 다른 라이브러리 중에 데이터 모델 인터페이스나 BaseAPI에 대한 파일이 별도로 만들어지는 경우도 있어서 이쪽을 선호할 수도 있다.

나에게 맞는 API 제너레이터를 찾아보자

API를 문서로 공유하면서 불편함이 있었다면, API 제너레이터를 사용해 보자. API 문서 작업이 자동화되어 복잡한 작업이 줄고, 생산성이 기하급수적으로 높아질 것이다. API 관련 논의를 하자마자 곧바로 메서드가 코드로 구현되는 것을 경험하고 나면, 아마 이전으로 돌아가고 싶지 않게 될 것이다. API 제너레이터의 장점은 단순히 효율성 향상에서 그치지 않는다. 자동화된 문서화 방식은 사람의 실수로 인해 발생할 수 있는 누락이나 오류를 방지해 주기도 한다.

만약 타입스크립트 API 제너레이터를 찾고 있는 개발자라면, 특히 단순함을 선호한다면 swagger-typescript-api를 추천한다. 이 라이브러리는 타입스크립트와의 뛰어난 호환성을 자랑하며, 각 API의 세부 사항들을 명확하게 타입으로 추출한다. 이는 백엔드와 프론트엔드 개발자 간의 정확한 커뮤니케이션을 가능하게 하고, 개발 과정에서의 혼란을 줄여줄 수 있다.

타입스크립트가 아닌 다른 언어로 API 클라이언트를 구축해야 한다면, 언어 특성에 맞는 라이브러리를 찾아보자. 이때 어떤 옵션들이 제공되는지 꼼꼼히 살펴보는 것이 좋다. 탐색 과정에서 자신이 평소 어떤 부분에서 불편함을 느꼈는지, 어떤 점이 개선되길 원했는지도 알 수 있게 된다.

어떤 경우에는 API 제너레이터가 개발 환경 자동화의 시작점이 될 수도 있다. 이것은 일종의 포맷 변환 과정이며, 서로 다른 포맷을 맞추는 것은 개발할 때 주로 병목으로 작용하는 부분이다. 만약 JSON 스키마 파일을 OAS 규격에 맞는 JSON이나 YAML 파일로 변환하고, 다시 API 파일로 변환하는 작업이 자동화된다면 병목이 사라지는 셈이다. 이러한 생산성의 향상은 개발팀에 큰 원동력이 되어 줄 것이다.