swagger-to-rq

v1.2.10

Published

4 days ago

Convert Swagger API specs into TypeScript Interfaces and TanStack Query hooks in one command.

0High
0Medium
0Low

s0ojin

swagger react-query tanstack-query typescript cli automation

swagger-to-rq (gen-rq) 🚀

Swagger API 명세를 기반으로 TypeScript 타입(Interfaces)과 TanStack Query(React Query v5) 커스텀 훅을 AI를 통해 1초 만에 자동 생성하는 강력한 CLI 도구입니다.

swagger-to-rq는 반복적이고 번거로운 API 연동 코딩 작업을 자동화합니다. 단순 HTTP 메서드 분석에 의존하지 않고, LLM(대형 언어 모델)이 API 경로와 요약을 기반으로 문맥(조회 vs 상태조작)을 이해하여 useQuery와 useMutation을 정확하게 판별해 줍니다. 또한 기존 코드와의 스마트 병합(Smart Merge) 기능을 제공하여, 이미 작성된 파일의 코드가 유실되지 않고 추가/수정된 사항만 깔끔하게 동기화됩니다.

주요 특징

🧠 문맥 기반 AI 판별: HTTP 메서드(예: POST 조회 API 등)에 구애받지 않고, API 설명과 경로의 뜻을 파악하여 useQuery 혹은 useMutation 훅으로 올바르게 자동 전환합니다.
🔄 스마트 병합 엔진 (Smart Merge): 기존 코드 파일을 덮어쓰지 않고, 새로운 API 및 타입은 추가하고 동일한 타입/API/훅은 지능적으로 업데이트하며 중복 임포트(Import)를 깔끔하게 해소합니다.
📂 정밀한 파일 구조 생성: 하나의 큰 훅 파일 대신, 도메인별 폴더 하위에 훅별 개별 파일(use[Name].ts)을 만들고 자동으로 index.ts에 배럴 익스포트(Barrel Export) 처리를 해 줍니다.
🔒 다중 LLM 프로바이더 지원: 무료이자 완벽한 오프라인 보안을 보장하는 로컬 Ollama, 업계 표준 OpenAI, 초고속 Google Gemini, 그리고 커스텀 OpenAI 호환 API 서버를 지원합니다.
📶 자동 재시도 메커니즘: OpenAI나 Gemini 무료 플랜에서 빈번히 발생하는 Rate Limit(HTTP 429/503) 에러 시, 공급자별 스마트 딜레이를 적용해 자동으로 재시도하여 중단 없는 배치를 보장합니다.

설치 및 실행 방법

swagger-to-rq는 별도의 영구 설치 없이 npx로 즉시 실행할 수도 있고, 프로젝트에 설치(글로벌/로컬)하여 실행할 수도 있습니다.

1. 설치 없이 바로 실행 (추천 🚀)

컴퓨터나 프로젝트에 패키지를 저장하지 않고, 항상 최신 버전으로 즉시 실행하고 싶을 때 사용합니다.

npx swagger-to-rq

(패키지에 단일 실행 파일이 포함되어 있어 npx swagger-to-rq 입력 시 자동으로 실행기가 작동합니다.)

2. 글로벌 설치 후 실행

시스템 전역에 설치하여 gen-rq 명령어를 언제든 바로 실행합니다.

npm install -g swagger-to-rq
gen-rq

3. 프로젝트 로컬 의존성 설치 후 실행

협업하는 프로젝트의 개발 의존성(devDependencies)으로 추가해 두고 실행합니다.

npm install -D swagger-to-rq
npx gen-rq

빠른 시작 (Quick Start)

가장 간단하게 시작하는 방법은 프로젝트 루트에 .env 파일을 생성하고 Swagger 정보 및 API Key를 입력한 뒤, 아래와 같이 인자 없이 실행하는 것입니다.

# 설치 없이 실행하는 경우
npx swagger-to-rq

[!NOTE] 인자(API 엔드포인트 경로) 없이 실행하면 친절한 가이드가 제공되는 대화형 인터랙티브 모드로 진입합니다.

디렉터리 출력 구조

gen-rq가 실행되면, 현재 실행한 작업 디렉터리(process.cwd())를 기준으로 다음과 같이 깔끔하게 정돈된 아키텍처에 맞추어 파일이 자동 생성/병합됩니다.

src/
├── apis/
│   ├── instance.ts          # (사전에 정의되어 있어야 하는 공통 axios 인스턴스)
│   └── [domain].ts          # 도메인별 API 요청 함수 (authApi, publicApi 사용)
├── models/
│   └── [domain].ts          # 도메인별 Request/Response TypeScript Interface
└── hooks/
    └── [domain]/
        ├── index.ts         # 도메인 하위의 모든 훅들을 export * 해주는 Barrel File
        ├── useXxx.ts        # 개별 useQuery 또는 useMutation 훅 파일
        └── useYyy.ts

[!TIP] 도메인(Domain) 판별 기준: CLI는 API 엔드포인트 경로(예: /api/v1/settlement/list)를 파악하여 버전 뒤에 오는 세그먼트(settlement)를 도메인명으로 기본 사용합니다. 만약 적절한 세그먼트가 없는 경우 첫 번째 세그먼트를 사용하며, 인터랙티브 모드에서 사용자가 직접 도메인명을 지정하거나 변경할 수도 있습니다.

환경 변수 (.env) 설정

매번 명령어에 API Key나 URL을 입력하지 않으려면, 프로젝트 루트에 .env 파일을 만들어 미리 채워둘 수 있습니다.

# 1. Swagger 명세 경로 (필수)
SWAGGER_URL=https://api.yourcompany.com/v2/api-docs

# 2. LLM 프로바이더 선택 (ollama, openai, gemini, custom 중 택 1)
LLM_PROVIDER=ollama

# 3. OpenAI 설정 시
OPENAI_API_KEY=sk-proj-xxxxxx
OPENAI_MODEL=gpt-5.4-mini
OPENAI_BASE_URL=https://api.openai.com/v1

# 4. Gemini 설정 시
GEMINI_API_KEY=AIzaSyxxxxxx
GEMINI_MODEL=gemini-3.5-flash
GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/

# 5. Ollama(로컬 무료 LLM) 설정 시
OLLAMA_MODEL=qwen3:4b
OLLAMA_BASE_URL=http://localhost:11434/v1

사용 방법

swagger-to-rq는 실행 방식에 따라 대화형 인터랙티브 모드와 일괄 명령어 모드를 모두 제공합니다.

1. 대화형 인터랙티브 모드 (Interactive Mode)

단순히 gen-rq를 입력하면 시작되며, 키보드 방향키와 입력창을 통해 손쉽게 진행할 수 있습니다.

gen-rq

이전 단계 돌아가기 기능: 값을 입력하는 도중 ..을 입력하거나 선택 목록에서 ◀ 이전 단계로 돌아가기를 선택하면 바로 직전 단계로 자연스럽게 되돌아가 값을 수정할 수 있습니다.
자동 추천 도메인: 입력한 API 경로를 분석하여 가장 어울리는 추천 도메인을 자동 추출하여 목록으로 보여주며, 직접 입력...을 통해 커스텀 도메인을 할당할 수도 있습니다.

2. 명령어 모드 (CLI Options Mode)

CI/CD 파이프라인이나 스크립트 기반 연동을 원할 때는 다음과 같이 명령어와 옵션을 조합하여 일괄 실행할 수 있습니다.

gen-rq [apiPath] [options]

아규먼트 (Arguments)

apiPath (선택): 변환하려는 특정 API 엔드포인트 경로입니다. (예: /api/v1/settlement/list)
- 단, --all 옵션 사용 시에는 생략이 가능합니다.

옵션 (Options)

실행 예시

A. Ollama(로컬 모델)로 특정 API 단일 생성

gen-rq /api/v1/user/profile -p ollama -m qwen3:4b

B. OpenAI를 사용해 모든 Swagger API 일괄 생성 (속도 최적화 모드)

gen-rq --all -p openai -k sk-proj-yourkey -m gpt-5.4-mini

C. Gemini를 활용해 특정 조회 API를 useQuery 훅으로 강제 강제 생성

gen-rq /api/v1/logs/search -p gemini -t query

핵심 기능 상세

스마트 병합 엔진 (Smart Merge Engine)

gen-rq는 단순 파일 덮어쓰기 도구가 아닙니다. 기존 프로젝트에 코드가 이미 존재하고 있다면 다음 로직에 의거해 코드를 안전하고 똑똑하게 병합합니다.

타입/인터페이스 병합 (models):
- 새로 생성된 타입명과 기존 타입명을 스캔합니다.
- 기존 파일에 존재하던 타입은 새 타입의 속성 구조로 깔끔하게 교체(Override)되며, 기존에 없던 신규 타입은 파일 하단에 덧붙여집니다.
API 함수 병합 (apis):
- 동일한 API 요청 함수(export const getSettlementList 등)가 이미 존재할 경우, 해당 함수의 본문 전체를 최신 스펙으로 교체(Override)합니다.
중복 없는 임포트 정돈 (Import Resolution):
- 파일 상단의 import 구문들을 정밀 분석하여 중복되거나 난잡해진 파일 경로 및 모듈 임포트를 단일 라인으로 통폐합하고 가나다 순으로 자동 정렬합니다.
- import type { ... } 과 일반 import { ... } 를 완전히 구별하여 번들 크기 및 타입 결합도를 최소화합니다.

개별 훅 파일 분리 및 자동 배럴 내보내기 (Barrel Export)

일반적인 CLI가 하나의 큰 파일에 모든 커스텀 훅을 몰아넣는 것과 달리, swagger-to-rq는 파일 관리와 코드 가독성을 위해 다음과 같이 작동합니다.

AI가 반환한 통합 훅 코드를 export const useXxx 선언문 단위로 정교하게 쪼갭니다.
쪼개진 훅 본문에서 실제 사용되고 있는 외부 컴포넌트나 타입(models 경로 내의 DTO 인터페이스 등)만 골라내어, 해당 훅 파일 상단에 필요한 import만 깔끔하게 주입합니다.
도메인 폴더(예: src/hooks/settlement/) 내에 useXxx.ts, useYyy.ts 처럼 개별 훅 파일로 저장합니다.
해당 폴더의 index.ts 파일을 검사하여 새롭게 생성된 훅의 export * from './useXxx'; 구문을 누락 없이 자동으로 추가해 줍니다. (기존에 이미 존재하는 내보내기 문구는 유지 및 중복 방지)

사내망 데이터 보안 가이드

코드를 자동 생성할 때, 개발 중인 사내 API 명세(Swagger JSON 스펙)가 AI의 컨텍스트로 전달됩니다. 이에 따라 다음과 같은 보안 수칙을 권장합니다.

Ollama (추천 ⭐⭐⭐):
- 사용자 로컬 PC 혹은 사내 GPU 서버 환경에서 오프라인으로 모델이 구동됩니다.
- 데이터가 외부망으로 전혀 유출되지 않으므로, 보안 규정이 엄격한 대기업 및 금융권망에서도 100% 안전하게 도입하여 사용할 수 있습니다.
OpenAI (API 가입자 기준):
- OpenAI의 API(ChatGPT 웹 아님)를 통해 전송된 프롬프트 데이터는 OpenAI 정책상 사용자 모델 학습에 활용되지 않고 안전하게 폐기됩니다.
Google Gemini (Free API 주의):
- 무료 티어의 Gemini API Key를 사용할 경우 Google 서비스 약관에 의거하여 데이터 일부가 모델 검토 및 학습에 활용될 가능성이 존재하므로, 민감 정보가 포함된 프로젝트에서는 가급적 사용을 피하거나 Ollama를 권장합니다.

API 속도 제한(Rate Limit) 대응 재시도 엔진

특히 무료 LLM API(예: Gemini Free)나 엄격한 초당 요청 한도(RPM)가 걸려있는 계정으로 모든 API 명세를 생성할 때(--all 옵션), 일시적으로 요청 거부 에러(HTTP 429 혹은 503)가 자주 발생할 수 있습니다.

swagger-to-rq는 이를 완벽히 대비해 설계되었습니다.

자동 감지: 호출 도중 429 Too Many Requests 혹은 503 Service Unavailable이 감지되면 자동으로 요청을 일시중지합니다.
스마트 재시도: 3회까지 동일 호출에 대해 백오프 딜레이를 두고 재시도합니다.
최적의 엔진 대기시간:
- Ollama: 로컬 실행이므로 엔진 대기시간을 100ms로 극도로 낮추어 속도를 극대화합니다.
- OpenAI / Custom: 안정적인 유료 요청을 보장하기 위해 도메인 간 1.5초 및 에러 재시도 시 5초 대기 정책을 취합니다.
- Gemini: 무료 API의 15 RPM 한도를 극복하기 위해 도메인 완료 시마다 자동으로 **6초의 쿨다운 지연(Cool-down Delay)**을 부여하며, 실패 시 15초 대기를 적용해 중간에 멈춤 없이 끝까지 완성되도록 조율합니다.

라이선스

This project is licensed under the MIT License.