OpenApi3ToZodConvert converter = new OpenApi3ToZodConvert("your_openapi_url_here"); var openApi3 = converter.getOpenApi3(); var handlerManager = converter.getTypeHandlerManager();최근 개인 프로젝트로 swaggerToZod라는 작은 도구를 통해 Swagger 자동화 Zod 자동화 문서 생성했습니다.
이 라이브러리는 OpenAPI 3 문서를 기반으로 Zod 스키마와 TypeScript 타입을 자동 생성하기 위한 것이다.
프로젝트 주소:
👉 https://github.com/NamChulJin/swaggerToZod
GitHub - NamChulJin/swaggerToZod
Contribute to NamChulJin/swaggerToZod development by creating an account on GitHub.
github.com
이 글에서는 GitHub 리포지토리에 있는 정보만 정확하게 정리해서 소개한다.
만들게 된 이유
swaggerToZod를 만든 목적은 두 가지였다.
1. 프론트엔드–백엔드 의사소통 부담을 줄이기 위해
API 스키마가 변경될 때마다
- 프론트엔드 타입 수정
- 백엔드 문서 수정
- 서로 다시 확인
하는 불필요한 소통 과정이 계속 반복되고 있었다.
OpenAPI 문서를 기준으로 Zod 스키마를 자동 생성할 수 있다면
프론트와 백엔드가 같은 스키마를 공유하게 되고,
의사소통 비용을 크게 줄일 수 있다.
2. 클라이언트(프론트엔드)에서 Zod 사용성을 높이기 위해
Zod는 런타임 타입 검증에 매우 유용하지만
OpenAPI 문서 내용을 Zod로 수동 변환하는 것은 번거롭다.
그래서:
- OpenAPI 문서를 읽어
- Zod 스키마를 자동 생성하고
- z.infer<> 기반 타입스크립트 타입까지 동시에 생성하는
도구가 필요했고, 이것을 직접 만들게 됐다.
프로젝트 구조 (GitHub 기준)
GitHub의 README.md와 소스 구조를 기준으로 소개한다.
(※ 존재하지 않는 정보는 절대 추가하지 않음)
✔ 사용 환경
리포지토리에 명시된 환경:
- Java 21 이상
- Spring Boot 기반에서 사용 가능
- ./gradlew clean build 실행 시
build/libs/swaggerToZod-<version>.jar 생성
✔ 주요 패키지 구성
1. convert 패키지
- OpenApi3ToZodConvert
- OpenAPI 3 문서(URL)를 로드하고
변환에 필요한 매니저/객체를 준비한다.
- OpenAPI 3 문서(URL)를 로드하고
핸들러 관련 클래스들도 함께 존재한다.
2. generator 패키지
- ZodGenerator
- Zod 스키마 및 TypeScript 타입 코드를 생성하는 핵심 클래스
- 다음 기능 제공:
- 전체 스키마 문자열 생성
- refName 기준 스키마 맵 생성
- 원본 변환된 스키마 맵 조회
- ZodData
- 형태화된 Zod 코드 데이터를 저장하는 DTO
3. manager 패키지
- ZodTypeHandlerManager
- 스키마 타입(string, object, array, oneOf 등)에 따라
적절한 핸들러를 선택하는 매니저
- 스키마 타입(string, object, array, oneOf 등)에 따라
- ZodSchemaCacheManager
- 스키마 변환 결과를 캐싱하여 중복 변환 방지
4. resolver 패키지
- ZodSchemaDependencyResolver
- $ref 관계를 분석하여 의존성을 해결하는 역할
5. sort 패키지
- SchemaDependencySorter, ZodSchemaSort
- 스키마 간 의존성을 기반으로 적절한 순서로 정렬
6. util 패키지
- CommonUtils
- 문자열 변환 등 공통 유틸리티 제공
7. format 패키지
- ZodFormatter, ZodFormatOptions
- 생성된 Zod 코드의 포맷을 맞추는 역할
위 정보는 모두 GitHub 리포지토리의 실제 파일 기반이다.
기본 사용법 (README 기준)
OpenApi3ToZodConvert로 OpenAPI 문서를 로드한 뒤,
ZodGenerator로 Zod 스키마를 생성한다.
OpenAPI 3 문서 로드
OpenApi3ToZodConvert converter = new OpenApi3ToZodConvert("your_openapi_url_here");
var openApi3 = converter.getOpenApi3();
var handlerManager = converter.getTypeHandlerManager();Zod 스키마 생성
ZodGenerator generator = new ZodGenerator(openApi3, handlerManager);
// 전체 Zod 스키마 코드
String result = generator.generateZodSchemas();
// refName 기준 Zod 스키마 맵
Map<String, String> fileMap = generator.generateZodSchemaMapByRefNames();
// 변환된 원본 스키마 맵
Map<String, ZodData> convertedSchemaMap = generator.getConvertedSchemas();
변환된 정보로 Swagger Zod 정보 확인 할 수 있도록 Zod Schema 팝업생성했습니다.
API별 Zod 추가적으로 생성했습니다.
swaggerToZod 사용의 실제 효과
✔ 프론트엔드에서 Zod 기반 타입 정의 속도가 크게 빨라진다
프론트엔드 입장에서 가장 큰 장점은,
Zod 스키마와 타입 정의를 직접 작성할 필요가 없어진다는 것이다.
- OpenAPI 문서만 준비되어 있으면
- Zod 스키마와 TypeScript 타입을 자동으로 생성할 수 있고
- 개발자는 생성된 파일을 가져다 바로 사용하면 된다
즉, 프론트엔드는 API 타입을 손으로 작성하는 과정을 통째로 생략할 수 있다.
그 결과:
- 타입 정의 시간 단축
- API 구조 변경에 대한 대응 속도 향상
- Zod 스키마 작성의 번거로움 해소
- 개발 중 오류 발생 가능성 감소
특히 Zod를 적극적으로 사용하는 프로젝트라면 효과가 매우 크다.