들어가며
Sopt에서 Lococo를 개발하면서 스웨거가 단순히 문서화 툴일 뿐만 아니라, 클라쪽에서 자동화로 뽑아서 코드를 작성해줄 수 있는 툴이 있음을 알게되었었다. 그래서 NestJS의 공식 문서를 보다가, 흥미로운 내용이 있어서 포스팅을 작성하게 되었다. @nestjs/swagger, FastAPI, Springdoc-openapi 같은 것들이 대표적인데, 이런 프레임워크들은 컨트롤러/라우트 정의를 읽어서 OpenAPI 문서를 뽑아주기까지 할 수 있다.
https://docs.nestjs.com/openapi/introduction
Documentation | NestJS - A progressive Node.js framework
Nest is a framework for building efficient, scalable Node.js server-side applications. It uses progressive JavaScript, is built with TypeScript and combines elements of OOP (Object Oriented Programming), FP (Functional Programming), and FRP (Functional Rea
docs.nestjs.com
본문
먼저 위처럼 타입 정의를 뽑아서 쓸 수 있다.
--no-client: API 클래스는 생성하지 않겠다는 의미이다
--union-enums: enum을 실제 TypeScript 유니온("A" | "B")으로 생성
이렇게 만들어진 marketplace.d.ts는 프로젝트 어디에서나 타입으로만 소비할 수 있다.
즉, 이 방식은 “타입 동기화” 측면에서만 도움을 줄 수 있고, 결국 API 호출부는 매번 손으로 짜야 하는 방식이다
swagger-typescript-api 활용하기
swagger-typescript-api가 제공하는 두 가지 커스터마이징 포인트를 이용하면, 위 문제를 꽤 깔끔하게 풀 수 있다.
- 템플릿(ejs) 커스터마이징
- 훅(hooks) 기반 플러그인 스타일 커스터마이징
1단계 – 기본 템플릿 뽑아서 레포에 복사
먼저, 공식 CLI가 제공하는 generate-templates 서브커맨드로 현재 버전의 기본 템플릿을 로컬에 복사한다
이렇게 하면 ./tools/swagger-templates 아래에 대략 이런 파일들이 생성된다.
- http-client.ejs
- data-contracts.ejs
- api.ejs
- (기타 헬퍼 템플릿들)
2단계 – http-client 템플릿에서 axios 인스턴스 주입 구조로 변경
http-client.ejs를 열어서 대략 아래와 비슷한 형태의 코드를 확인한다.
서론에서 얘기했듯이, “이미 만들어 둔 axios 인스턴스를 주입해서 쓰는 형태”로 활용하기 위해서 템플릿을 살짝 바꿔준다
3단계 – API 템플릿에서 메서드 이름과 반환 타입 컨벤션 정리
다음으로 api.ejs 쪽에서 메서드 이름과 반환 타입을 팀 컨벤션에 맞게 정리한다.
예를 들어, 기본 템플릿은 GET /v1/tickets 같은 엔드포인트를 getTickets 대신 ticketsControllerControllerListTickets 같은 장문의 이름으로 만들 수도 있다.
- 태그(tag) + HTTP 메서드 + 경로 일부 조합으로 깔끔하게 축약
- operationId를 우선적으로 사용해서 백엔드에서 이름을 명시적으로 관리
4단계 – hooks 로 스키마/타입 수정하여 플러그인처럼 사용
위 소스코드처럼, onParseSchema, onCreateRouteName 등 다양한 훅을 조합하면 enum, 날짜 타입, 파일 업로드 타입 등을 우리 코드베이스에서 쓰는 타입으로 일괄 매핑 가능하다. 사실상 “젠 체인 앞단에서 동작하는 플러그인”처럼 사용이 가능해진다
마치며
이제 전체 플로우를 정리하며 글을 마무리 해보려고 한다.
- 서버에서 OpenAPI 스펙 자동 생성
- NestJS, Spring, FastAPI 등에서 /v3/api-docs, /openapi.json 등으로 노출
- CI에서 swagger-typescript-api 실행
- 템플릿 + hooks를 이용해 타입 + axios 클라이언트 코드 생성
- 프론트/공유 라이브러리가 그 코드를 그대로 import
- 레포 간에는 git submodule, 패키지 배포 등으로 공유
결론적으로 스웨거 스펙을 최신 상태로 유지해주면, 타입 + axios 기반 클라이언트 코드가 함께 갱신되고 프론트/다른 서비스에서는 MarketplaceClient만 가져다 쓰면 되는 자동화 구조를 만들 수 있다.
참고 & 공식문서 링크
- OpenAPI 공식 스펙 (3.1 기준)
https://swagger.io/specification/ - OpenAPI 3.0 Paths & Operations 설명
https://swagger.io/docs/specification/v3_0/paths-and-operations/ - swagger-typescript-api GitHub 리포지토리
https://github.com/acacode/swagger-typescript-api