SwaggerAutomation

Swagger-to-Typescript (axios)

최정은
2023/08/31
목차

도입 배경

경험으로는 FE개발은 프로젝트의 마침표.

PM & Design & BE의 산출물을 예쁘게 포장하여 유저에게 제공.

SaaS 데모를 준비하면서 생각을 하게되었음.

마지막까지 스펙 & API가 변경될 가능성이 높아보임. → 이러다 죽겠다 !

사람 손을 덜수 있는것을 찾아보자 !

이전에 GraphQL을 사용하여 개발을 할때, GraphQL Code Generator를 동료가 만들어서 유용하게 사용한 경험이 있음. → 나도 한번 만들어보자 ~!

Swagger UI

  • BE 개발자가 작성해주는 API 명세
  • 각 API의 path와 method, parameter, requestbody, response를 정의
  • 스키마를 작성하여 각 요청과 응답에 필요한 DTO 정의
  • UI로 확인 및 테스트 가능

OpenAPI Specification

  • Swagger 문서를 작성하는 스펙

개발 전에 고민하였던 점.

만들면 사용할까 ? 무슨 이점이 있을까 ?

Untitled.png

AS-IS

  1. Swagger 문서 제공
  2. API의 method 그리고 Parameter, RequestBody, Response DTO 확인
  3. Request, Response Type정의
  4. Api Fetch함수 작성
  5. Fetch함수 사용

TO-BE

  1. Swagger 문서 제공
  2. Code Generator 실행
  3. Fetch함수 사용

단순하게 생각해보면 2,3,4 과정을 생략 할 수 있으니 손을 덜수 있을것 같다는 판단.

손을 덜게되면 다른 커뮤니케이션 비용 혹은 개발하는 시간에 좀 더 투자를 할수 있을것 같다.

만들수 있을까 ?

여러 문서 리서치

음… 자료도 많고 일단 해보자!

분명 사용하다보면 BE개발자분들께 Swagger 문서에 수정을 요청하게 될텐데 충분한 협의를 할수 있을지 ?

  • @SaaS-TF BE > 동의해주심…ㅎ

어떤 라이브러리를 사용할지 ?

(2023.09.01 기준)

| | Star | Weekly downloads | Last publish | Typescript 지원 | Api 자동생성 | Template | | ------------------------- | ---- | ---------------- | ------------- | ------------- | -------- | --------- | | openapi-generator-cli | 1k | 407,531 | a month ago | O | O | mustaches | | openapi-typescript | 3.5k | 481,369 | a day ago | O | O | X | | swagger-typescript-api | 2.3k | 124,500 | 22 days ago | O | O | ejs | | json-schema-to-typescript | 2.5k | 398,942 | 2 days ago | O | X | X |

대부분의 라이브러리가 유지보수가 잘 되고있고, Star도 많고, 문서화도 잘되어있었다.

petstore3 문서를 사용하여 몇가지 테스트를 해보았다.

  1. 타입이 잘 생성되는가 ?
  2. api는 어떻게 생성이 되는가 ?
    1. 커스터마이징이 되는가 ?
      1. 된다면 어떻게 할수 있는지 ?

타입 생성은 당연하게도 모두 잘되었다.

하지만 api생성의 경우 openapi-generator-cli와 swagger-typescript-api만 지원을 하였다.

두 라이브러리 모두 api 템플릿도 제공을 하였다.

다만, mustaches문법과 ejs문법을 사용해서 템플릿을 수정할수 있었다.

두 문법 모두 학습비용이 들었던 나에게는 거부감이 있었고, 또 일부 문법에서는 지원하지 않는 기능들이 있다면 라이브러리를 통해 생성된 데이터들을 재가공해서 사용해야할수도 있다는 걱정이 컸다.

그러다가 발견한 라이브러리가 json-schema-to-typescript이다.

JSON Schema 스펙의 JSON객체로부터 Type을 추출해주는 라이브러리이다.

대부분의 라이브러리가 OpenAPI Spec > JSON Schema > Typescript와 같은 방식으로 변환을 하고 있었고, 여러 이유로 json-schema-to-typescript 라이브러리를 이용해서 파싱을 직접 하기로 결정하였다.

  1. 타입이 잘 생성 되어야함
  2. API 커스터마이징이 되어야함
    1. 문법이 쉬워야함

어디까지 자동화를 할지 ?

  1. *타입 추출
  2. *API 추출
    1. Fetch
    2. Axios
    3. React-Query

@teddy의 좋은 의견이 있었고, API함수까지만 자동화를하고 React Query Hook은 Hook의 용도와 개발자 각자의 취향에 맞게 작성하는것을 추천해주셨다.

이 부분에 대해서는 나도 공감을하게 되었다. ReactQuery는 스펙에 따라 다양한 옵션을 주어 처리를 해야하는 일이 잦기 때문이었다.

그렇다면 fetch와 axios중에 선택을 필요.

Swagger문서로부터 API Path, method, Header, Parameter, RequestBody, Response등만 뽑아낼수 있다면 어떤 메소드를 구성해도 문제가 없을거라고 판단하였고

CDPP 프로젝트에서는 axios를 먼저 만들어보기로 결정하였다.

유지보수는 ?

사용을 하다보면 Swagger Spec과 JSON Schema 스펙을 전부 대응을 하지 못했을 가능성이 크다고 생각.

Type과 Fetch함수 정도만 생성을 할것임, 비즈니스 로직이 들어가지는 않을테니 손쉽게 걷어낼수도 있을거라고 판단하였다.

발생하는 이슈는 최대한 대응을 해보는걸로 !

JSON Schema > Generic 지원안함 ㅠ.ㅠ

실행 과정

사전지식

Untitled.png

  1. Swagger Docs 가져오기.
    1. Config에 Json URL등 설정
  2. Swagger Docs JSON을 JSON Schema로 변환하기.
    1. Schema Parser를 통해 $ref 파싱 및 변환 #/components/schemas → OAISchema.json#/components/schemas
  3. JSON Schema로 부터 Type 추출하기. jsonschema-to-typescript 사용
  4. Swagger Docs의 paths 파싱하기.
    1. document.paths[path][method]
      1. parameters
      2. requestbody
      3. responses
    2. 각 path별 param, requestbody, response 매핑
  5. api template 작성하기.
    1. 4.에서 파싱한 정보를 사용하여 Fetch함수 작성

장점과 단점

장점

  • Swagger문서만 잘되어있다면 타입 및 API Fetch 함수를 작성하지 않아도 되니 생산성 증가
  • 생산성 증가 → 커뮤니케이션 비용 혹은 개발 비용에 투자 가능

단점

  • 유지보수를 추가로 해야한다.
  • 컨벤션이 제한적이다.
    • swagger-to-typescript에 적혀있는대로만 사용가능 -_-
      • 옵셔널하게 개발을…
  • Swagger문서가 잘되어있지 않다면 커스터마이징이 많아진다.
    • ex) fetch함수명 (operationId를 사용중인데 문제가 있음..)