amaranth.log
💻 개발

Swagger 문서 기반 타입 자동 생성으로 프론트엔드 API 연동 자동화하기 (feat. swagger-typescript-api)

서론

최근 회사에서 프론트엔드 동료가 API의 DTO 타입을 관리하는 번거로움을 개선하기 위해 swagger-typescript-api라는 타입 정의 자동화 라이브러리를 도입했다.
기존에 백엔드에서 API 변경사항이 생기면, 백엔드 담당자분으로부터 1. 변경사항에 대한 명세를 전달받고 2. 명세에 맞게 DTO 타입 정의를 생성/수정/삭제한 뒤 3. 그 여파로 발생한 타입 오류를 추적해 고쳐주는 작업을 수행해야 했다.
사실상 백엔드 로직으로 한 번 작성한 DTO 명세를 프론트에서 한 번 더 작성하는 구조이기 때문에 관리 포인트가 두 개로 분산되어 있었고, 이것은 Next.js같은 풀스택 프레임워크를 사용하는 게 아니라면 모든 개발자들이 경험할 수밖에 없는, 어쩔 수 없는 병목이었다.
당시 나와 동료는 다른 프로젝트에 참여하고 있었지만, 나도 동료의 프로젝트에 참여할 일이 있어 해당 라이브러리가 도입된 개발 프로세스를 경험해볼 수 있었다. 직접 사용해보니 API 타입 동기화 작업을 상당부분 자동화할 수 있었고, 반복적인 수작업이 줄어들면서 생산성이 크게 향상된 걸 체감할 수 있었다.
마침 우리 프로젝트도 같은 문제를 가지고 있었기 때문에, 이번 기회에 swagger-typescript-api를 직접 도입해보았다. 이 글에서는 그 과정을 정리해보려고 한다.

🤔 swagger-typescript-api?

swagger-typescript-api는 Swagger(OpenAPI) 문서를 입력으로 받아서, 타입이 포함된 API 호출 코드를 자동으로 생성해주는 라이브러리이다.
💡
Swagger?
Rest API의 명세를 표준화된 형식으로 정의하고, 문서와 테스트까지 가능하게 해주는 도구.
마침 우리 회사의 모든 프로젝트는 API 문서화 도구로 Swagger를 사용하고 있다. swagger-typescript-api말고도 swagger 문서를 기반으로 타입을 자동 생성해주는 라이브러리가 더 있긴 한데, 그 중 swagger-typescript-api가 가장 직관적이고 일관성 있는 타입을 산출할 수 있어서 채택했다.

🔧 셋팅 과정(v13.2.16 기준)

설치

npm i swagger-typescript-api ## or yarn add swagger-typescript-api

package.json에 커맨드 추가

"swagger": "swagger-typescript-api generate -p {Swagger 문서 Path!} -o {생성 결과로 지정할 경로}",
  • -p {Swagger 문서 Path!}: 정보를 가져올 swagger 문서의 경로를 지정하는 옵션이다. url, 로컬경로 모두 가능하다.
  • -o {생성 결과로 지정할 경로}: Output 경로를 지정하는 옵션이다.
  • 추가 옵션
    • -r: request reponse 에 대한 더 자세한 정보를 생성하겠다는 옵션이다.
    • --modular: OpenAPI의 tag 단위로 파일을 쪼개는 옵션이다. 이 옵션이 없으면 Api.ts 파일에 모든 api 호출 함수가 정의되고, 옵션을 설정해주면 모듈로 분리된다.
    • -d: 기본 response의 값을 success시의 response값으로 지정하겠다는 옵션이다.
    • --extract-request-body --extract-response-body --extract-response-error: reqeust, response, error Type을 생성하는 옵션이다.
    • --no-client: API 호출 함수를 생성하지 않는 옵션이다.(타입 정의만 생성)
    • --axios: API생성시 axios함수로 생성하게하는 옵션이다.
 
실제로 작성한 커맨드는 다음과 같다.(보안상 swagger url은 자체 모자이크 처리했다.)
"swagger": "swagger-typescript-api generate -p https://********/swagger/v1/swagger.json -r -o ./src/types --modular -d --extract-request-body --extract-response-body --extract-response-error --axios",
 

실행 결과

notion image
notion image
Output 경로에 관련 파일들이 생성되는 모습을 볼 수 있다. 크게 http-client.ts, data-contracts.ts, 컨트롤러 별 클래스가 정의된 파일(편의상 컨트롤러 파일이라고 칭하겠다.) 이렇게 세 종류의 파일이 생성된다.

1. http-client.ts

axios 객체를 instance 프로퍼티로 가지고 있으며, axios 요청과 응답을 수행하는 래퍼 역할을 한다.

2. data-contracts.ts

swagger 명세로부터 자동 생성된 API 별 요청&응답 dto 인터페이스와 타입이 정의되어 있다.
생성되는 dto 타입은 swagger에 명세되어 있는 request(요청 payload 타입), response(응답 데이터 타입), error type(에러 응답 타입) 세 가지이다. error type의 경우 예시를 가져오진 못했지만 Swagger에 정의된 stauts code마다 생성된 응답 타입으로 Union Type을 생성한다고 한다. 참고로 인터페이스&타입 이름은 백엔드에서 정의된 DTO 클래스명을 따르는 듯하다.
notion image
notion image
타입 정의를 보면 Swagger에 정의되어 있던 응답 데이터의 스키마와 동일한 것을 확인할 수 있다.

3. 컨트롤러 파일

: 컨트롤러 파일은 API를 호출하는 메서드를 포함하는 클래스가 정의되어 있다. 이 클래스는 http-client.ts에서 정의된 HttpClient 클래스를 상속한다.
예시를 보여주기 위해 Filter.ts라는 컨트롤러 파일의 모자이크를 풀었다. 여기서 생성된 Filter.ts 파일은
notion image
Swagger에서 Filter라는 컨트롤러 섹션 내에 정의된 API를 호출하는 함수를 모아둔 파일이다.
사내 보안 상 구체적인 API 경로를 밝히기 어려워, 예시 GET API의 경로를 /Filter/bla-bla라고 가정하기로 하자.
notion image
Filter.ts 파일을 직접 들어가보면, Filter 컨트롤러의 api를 호출하는 함수가 정의되어 있는 것을 확인할 수 있다.
notion image
swagger-typescript-api는 swagger에 작성된 명세를 기반으로 타입을 정의해주기 때문에, dto 타이핑 작업을 자동화하려면 swagger에도 요청과 응답 데이터에 대한 타입 명세가 정의되어 있어야 한다.
notion image
위 코드를 보면 Swagger에 해당 API의 정상 응답(200)에 대한 타입 명세가 작성되어 있어 BlaBlaListData라는 타입이 자동 생성된 반면, 에러 응답(400 등)의 타입은 Swagger에 명세가 작성되어 있지 않기 때문에 any 타입으로 지정된 것을 볼 수 있다.
notion image
BlaBlaListData라는 응답 데이터 타입은 data-contracts.ts 파일에 정의된 타입을 참조한다.

레거시 API 호출 로직 마이그레이션하기(with. Claude Code)

API 호출 로직 수정하기

이렇게 타입과 api 호출 함수를 만들었다면, 이제는 이것들을 실제 api를 사용하는 로직에 적용해야 한다.
처음 프로젝트를 개발할 때부터 이 라이브러리를 적용했다면 몰라도, 지금 내가 참여하고 있는 프로젝트는 유지보수 단계에 있는, 즉 실제 운영 중인 서비스이기 때문에, 기존 레거시 로직이 라이브러리가 만든 타입과 api 호출 함수를 사용하도록 점진적으로 수정하는 작업이 필요했다.
기존의 우리 프로젝트에서 api를 정의하고 호출하는 함수는 다음과 같이 구현되어 있었다.
  1. axios 객체로 api를 호출하는 함수를 정의하고
  1. Tanstack query에서 제공하는 훅(useQuery, useMutation)을 API 목적에 맞게 사용하여 1에서 정의한 함수를 호출하는 커스텀 훅을 정의한다.
  1. 다른 컴포넌트와 훅에서 2에서 정의한 커스텀 훅을 사용한다.
const GetFilterBlaBlaApi = async (params: { // 1 trans: number; language: Language; }) => { const { data } = await defaultInstance.get('/Filter/bla-bla', { params, }); return data; }; export const useGetFilterBlaBlaQuery = (params: { // 2 trans: number; language: Language; }) => useQuery( [`FilterBlaBla`, params], () => GetFilterBlaBlaApi(params), { enabled: !!params.trans }, );
function TestComponent({ person, language }: { person: { id: number; content: string }; language: Language; }) { const { data } = useGetFilterBlaBlaQuery({ // 3 person: person.id, language, }); ...
💡
참고로 defaultInstance는 프로젝트 내 인증 헤더와 같은 API 호출 시의 공통 설정을 적용한 axios 객체이다.
import axios from 'axios'; import { getSession } from 'next-auth/react'; const axiosApi = (url: string, data?: any) => { const instance = axios.create({ baseURL: url, withCredentials: true, ...data, }); instance.interceptors.request.use(async config => { const session = await getSession(); if (session?.accessToken) { config.headers.Authorization = `Bearer ${session.accessToken}`; } return config; }); return instance; }; export const defaultInstance = axiosApi('/*********'); // 모자이크
swagger-typescript-api를 통해 1에 해당하는 함수와 DTO 타입 정의를 얻었으니, useGetFilterBlaBlaQuery() 훅이 swagger-typescript-api가 생성한 함수를 사용하도록 수정해야 한다.
이 때 Filter.ts의 Filter 클래스 객체를 그대로 쓰면 안되고, 기존에 사용했던 defaultInstance(axios 래퍼 인스턴스)에 정의된 설정을 그대로 가져가야 한다.
Swagger가 생성한 파일 중 http-client.ts에 정의된 HttpClient 클래스는 axios객체를 instance 프로퍼티로 가진다. HttpClient 클래스를 상속하는 모든 클래스(Filter.ts의 Filter 등)에 정의된 메서드는 이 instance를 통해 axios 요청을 보낸다. 즉, Filter.ts를 비롯한 swagger-typescript-api 라이브러리가 생성한 컨트롤러 별 클래스는 axios 객체의 wrapper 클래스라고 할 수 있다.
프로젝트의 defaultInstance와 동일한 설정을 적용한 Axios 객체를 instance로 갖는 클래스 객체를 생성하는 함수 createApiClient()를 만들고 모든 라이브러리 정의 클래스에 대해 인스턴스를 생성하고 export했다.
import { getSession } from 'next-auth/react'; // Swagger 생성 API 클래스들 ... import { Filter } from '@/types/Filter'; ... import { HttpClient } from '@/types/http-client'; /** * defaultInstance와 동일한 설정으로 API 클라이언트 생성 */ const createApiClient = <T extends HttpClient>(ApiClass: new (config?: any) => T): T => { const client = new ApiClass({ baseURL: '/*********', withCredentials: true, }); client.instance.interceptors.request.use(async config => { const session = await getSession(); if (session?.accessToken) { config.headers.Authorization = `Bearer ${session.accessToken}`; } return config; }); return client; }; // 도메인별 API 클라이언트 export ... export const filterApi = createApiClient(Filter); ...
swagger-client.ts
그리고 이 객체를 통해 기존 api 호출 함수를 정의했던 파일의 훅 함수를 정의해준다. 그럼 다음과 같은 형태가 될 것이다.
import { filterApi } from '@apis/swagger-client'; ... export const useGetFilterBlaBlaQuery = (params: { trans: number; language: Language; }) => useQuery( [`FilterBlaBla`, params], () => filterApi.blaBlaList(params).then(res => res.data), { enabled: !!params.trans }, );

실제 운영 중인 서비스에 점진적으로 마이그레이션하기

프로젝트에서는 워낙 많은 api를 사용하고 있기 때문에, 기존의 api 호출 로직을 전부 swagger-typescript-api 기반으로 마이그레이션하는 것은 꽤나 방대한 작업이었다. 여기서는 Claude Code의 도움을 받았다.
원활한 마이그레이션 작업을 위해 /swagger-migration이라는 커스텀 커맨드를 만들었다. 프로젝트에서 사용하는 모든 컨트롤러를 리스트업하고 진행 상황을 기록하면서 아직 마이그레이션되지 않은 컨트롤러에 대해 수시로 마이그레이션을 진행할 수 있게 구성했다.
# /swagger-migration 커맨드 swagger-typescript-api로 생성된 타입을 기반으로, 아직 마이그레이션되지 않은 API 도메인을 React Query 훅 구조로 전환합니다. ## 배경 기존에는 `src/apis/api/filter-api.ts`처럼 단일 파일에 API 함수, 타입, React Query 훅이 모두 혼재되어 있었고, DTO 타입도 수동으로 정의하고 있었습니다. 이 커맨드는 swagger-typescript-api가 자동 생성한 타입(`src/types/`)을 활용하여: - 수동 DTO 정의를 제거하고 - 도메인별 폴더 구조로 관심사를 분리하며 - 기존 인증 로직(NextAuth)과의 호환성을 유지한 채 점진적으로 마이그레이션을 수행합니다. --- ## Step 1: 마이그레이션 대상 파악 ### 1-1. swagger 도메인 클래스 목록 수집 `src/types/` 디렉토리에서 swagger-typescript-api가 생성한 도메인 클래스 파일 목록을 수집합니다. (`data-contracts.ts`, `http-client.ts` 제외) ### 1-2. 마이그레이션 완료 여부 판별 각 도메인에 대해 아래 조건을 확인합니다: | 조건 | 판별 | |------|------| | `src/apis/api/{kebab-domain}/index.ts` 존재 | 마이그레이션 완료 | | `src/apis/api/{kebab-domain}-api.ts`만 존재 | 미완료 (단일 파일 방식) | | `src/apis/api/` 아래에 대응 파일 없음 | 미완료 (훅 미정의) | ### 1-3. 사용자에게 목록 출력 미완료 도메인 목록을 표 형태로 출력하고, 마이그레이션할 도메인을 선택하도록 요청합니다. ``` ## 마이그레이션 대상 | # | swagger 클래스 | 현재 상태 | 기존 파일 | |---|---------------|----------|----------| | 1 | Filter | 단일 파일 | filter-api.ts | | 2 | SomeDomain | 훅 미정의 | — | | ... 마이그레이션할 도메인 번호를 선택해 주세요. (예: 1, 3) ``` --- ## Step 2: 마이그레이션 실행 사용자가 선택한 도메인 각각에 대해 아래 절차를 수행합니다. ### 2-1. swagger 클래스 분석 `src/types/{Domain}.ts` 파일을 읽고 메서드 목록을 파악합니다: - 메서드명, HTTP 메서드(GET/POST/PUT/DELETE) - 파라미터 타입 (query, path, body) - 리턴 타입 ### 2-2. swagger-client.ts 등록 확인 `src/apis/swagger-client.ts`에 해당 도메인 클라이언트가 없으면 추가합니다. ```typescript // import 추가 (알파벳 순) import { Filter } from '@/types/Filter'; // export 추가 (알파벳 순) export const filterApi = createApiClient(Filter); ``` ### 2-3. 도메인 폴더 생성 `src/apis/api/{kebab-domain}/` 폴더에 `index.ts`와 `types.ts`를 생성합니다. **폴더명은 swagger 클래스명을 케밥 케이스로 변환:** | swagger 클래스명 | 폴더명 | |---|---| | `Filter` | `filter/` | | `SomeDomain` | `some-domain/` | > 기능명이나 UI 이름이 아닌 swagger 클래스명 기준입니다. ### 2-4. types.ts 작성 API 함수의 입력 파라미터 인터페이스만 정의합니다. swagger 생성 타입의 re-export는 하지 않습니다. ```typescript import { CommonListParams } from '../types'; // API 파라미터 타입 정의 export interface GetFilterDetailParams { id: number; type?: string; } // 목록 조회는 CommonListParams 상속 export interface GetFilterListParams extends CommonListParams { startDate?: string; endDate?: string; keyword?: string | null; category?: number; department?: number | null; status?: number; } ``` **types.ts 작성 규칙:** - 기존 코드에서 `null`을 사용하는 필드는 `| null`을 허용 - 목록 조회 파라미터는 반드시 `CommonListParams`를 상속 - swagger 메서드의 query 파라미터를 camelCase로 변환하여 정의 - **swagger 생성 타입의 re-export 금지** — 필요한 곳에서 `@/types/data-contracts`를 직접 import ### 2-5. index.ts 작성 ```typescript import { filterApi } from '@apis/swagger-client'; import { toPascalCaseKeys } from '@apis/utils/toPascalCaseKeys'; import type { FilterItem, FilterListData, FilterDetailData } from '@/types/data-contracts'; import { AxiosError } from 'axios'; import { useQuery } from 'react-query'; import type { GetFilterDetailParams, GetFilterListParams } from './types'; // GET → useQuery 훅 export const useGetFilterDetailQuery = ( params: GetFilterDetailParams, options?: { enabled?: boolean }, ) => useQuery<FilterDetailData, AxiosError>({ queryKey: ['FilterDetail', params], queryFn: () => filterApi.filterDetail(params).then(res => res.data), ...options, }); export const useGetFilterListQuery = ( params: GetFilterListParams, options?: { enabled?: boolean }, ) => useQuery<FilterListData, AxiosError>({ queryKey: ['FilterList', params], queryFn: () => filterApi.filterList(toPascalCaseKeys(params)).then(res => res.data), ...options, }); // POST/PUT/DELETE → 직접 export export const PostFilterApi = async (data: FilterItem) => filterApi.filterCreate(data); export const PutFilterApi = async (data: FilterItem) => filterApi.filterUpdate(data); export const DeleteFilterApi = async (params: { id: number }) => filterApi.filterDelete(params.id); ``` **훅 작성 규칙:** - **GET** → `useQuery` 훅. 네이밍: `useGet{Domain}{Endpoint}Query` - **POST/PUT/DELETE** → async 함수 직접 export. 네이밍: `Post{Domain}Api`, `Put{Domain}Api`, `Delete{Domain}Api` - **queryKey**: 도메인 + 엔드포인트 조합 고유 문자열 - **toPascalCaseKeys**: query 파라미터가 있는 목록 조회에 적용 - **파라미터 타입은 반드시 types.ts에 별도 정의** (인라인 금지) - **swagger 생성 타입(DTO)은 `@/types/data-contracts`에서 직접 import** - **`as any` 사용 금지** `as any` 대신: | 상황 | 해결 방법 | |---|---| | swagger 반환 타입이 `any`일 때 | `as any` 없이 직접 접근 | | 요청 body 타입 불일치 | swagger 생성 타입(`data-contracts.ts`)으로 교체 | | swagger 응답 타입이 실제와 다를 때 | `as unknown as` + 실제 구조 타입 | | FormData 전달 | `as unknown as` + swagger payload 타입 | --- ## Step 3: 기존 파일 마이그레이션 ### 3-1. 기존 훅 사용처 탐색 기존 API 파일(`{domain}-api.ts`)에서 export되는 함수/훅을 Grep으로 검색하여 사용처를 파악합니다: - `src/containers/` - `src/pages/` - `src/components/` ### 3-2. import 경로 변경 ```typescript // Before import { FilterItem, FilterCategory, useGetFilterQuery, } from '@apis/api/filter-api'; // After import { useGetFilterQuery } from '@apis/api/filter'; import type { FilterItem } from '@/types/data-contracts'; import { FilterCategory } from './constants/types'; ``` ### 3-3. 타입 충돌 해결 swagger 타입과 UI 타입이 이름 충돌하는 경우: - UI 전용 타입에 `FormData` 접미사 추가 → `FilterItemFormData` - `src/containers/{domain}/constants/types.ts`로 이동 ```typescript // swagger 생성 타입 (API용) — 그대로 유지 interface FilterItem { id: number; categoryId: number; details: FilterItemDetail[]; } // UI 전용 타입 — 리네이밍 후 containers로 이동 interface FilterItemFormData { id: number; name: string; options: string[]; } ``` **주의: 타입 리네이밍 시 변수명까지 변경하지 않도록 타입 위치만 타겟팅** ```typescript // 타입 어노테이션만 변경 useState<FilterItem[]> → useState<FilterItemFormData[]> useRef<FilterItem[]> → useRef<FilterItemFormData[]> (item: FilterItem) → (item: FilterItemFormData) // 변수명은 유지 currentFilterItemIndex, handleAddFilterItem // 그대로 ``` ### 3-4. 기존 파일 삭제 모든 사용처 마이그레이션이 완료되면 기존 `{domain}-api.ts` 파일을 삭제합니다. --- ## Step 4: 빌드 검증 `yarn build`를 실행하여 타입 에러가 없는지 확인합니다. 에러 발생 시 해당 파일을 수정합니다. --- ## Step 5: 결과 보고 작업 완료 후 아래 항목을 정리하여 보고합니다: - **마이그레이션 완료 도메인**: 도메인명, 생성된 파일 목록 - **수정된 파일**: import 변경, 타입 리네이밍 등 - **삭제된 파일**: 기존 단일 API 파일 - **수동 확인 필요**: 자동으로 처리하지 못한 항목 (있을 경우) --- ## 참조 ### 최종 구조 ``` src/ ├── apis/ │ ├── index.ts # 기존 defaultInstance (유지) │ ├── swagger-client.ts # swagger API 클라이언트 래퍼 │ ├── utils/ │ │ └── toPascalCaseKeys.ts # camelCase → PascalCase 변환 │ └── api/ │ ├── types.ts # 공통 파라미터 (CommonListParams 등) │ └── {domain}/ # swagger 클래스별 폴더 │ ├── index.ts # API 함수 및 React Query 훅 │ └── types.ts # API 입력 파라미터 타입 │ ├── containers/ │ └── {domain}/ │ └── constants/ │ ├── types.ts # UI/비즈니스 로직 전용 타입 │ └── data.ts # 도메인 전용 상수 │ └── types/ # swagger-typescript-api 자동 생성 ├── data-contracts.ts # 모든 DTO 타입 ├── http-client.ts # HttpClient 베이스 클래스 └── {Domain}.ts # 도메인별 API 클래스 ``` ### 타입 분류 | 위치 | 역할 | 예시 | |------|------|------| | `src/types/data-contracts.ts` | swagger 자동 생성 DTO | `FilterItem`, `FilterListData` | | `src/apis/api/{domain}/types.ts` | API 입력 파라미터 타입 | `GetFilterListParams` | | `src/containers/{domain}/constants/types.ts` | UI 전용 타입 | `FilterItemFormData` | ### 참조 파일 | 파일 | 용도 | |------|------| | `src/apis/swagger-client.ts` | API 클라이언트 팩토리 및 export | | `src/apis/api/types.ts` | CommonListParams 베이스 타입 | | `src/apis/utils/toPascalCaseKeys.ts` | camelCase → PascalCase 변환 |
업무 중 여유가 생기는 틈틈이 컨트롤러를 한 두개씩 마이그레이션했다. 넉넉잡아 2달 정도 걸린 것 같다.
 

API 수정사항 빠르게 적용하기

마이그레이션된 컨트롤러에 대해 실제 API 변경사항을 쉽게 동기화할 수 있도록, API 동기화 커맨드(/swagger)를 하나 추가해주었다.
# /swagger 커맨드 Swagger 문서와 동기화하여 타입을 재생성하고, 새로운/변경된 API에 대한 React Query 훅을 자동으로 생성·수정합니다. ## Step 1: Swagger 타입 재생성 `yarn swagger`를 실행하여 `src/types/` 디렉토리의 타입 파일을 최신 swagger 문서와 동기화합니다. ### 1-1. data-contracts.ts 옵셔널 속성 제거 (후처리) `yarn swagger` 실행 후, `src/types/data-contracts.ts`의 모든 인터페이스 속성에서 옵셔널(`?`)을 제거합니다. ```bash sed -i '' 's/\([a-zA-Z0-9_"]\)\?:/\1:/g' src/types/data-contracts.ts ``` ## Step 2: 변경 사항 분석 `git diff --name-status src/types/`로 변경된 파일 목록을 확인하고, `git diff src/types/`로 구체적인 변경 내용을 파악합니다. 변경 파일 분류: - **A (Added)**: 새로 추가된 도메인 API → Step 3으로 - **M (Modified)**: 기존 도메인의 엔드포인트/타입 변경 → Step 4로 - 변경 없음: "swagger 문서에 변경 사항이 없습니다." 출력 후 종료 ## Step 3: 새 API 도메인 처리 새로 추가된 `src/types/{Domain}.ts` 파일 각각에 대해: ### 3-1. swagger-client.ts 업데이트 `src/apis/swagger-client.ts`에 새 도메인 클라이언트를 추가합니다. ```typescript // import 추가 (알파벳 순) import { Filter } from '@/types/Filter'; // export 추가 (알파벳 순) export const filterApi = createApiClient(Filter); ``` ### 3-2. API 훅 폴더 생성 `src/apis/api/{domain}/` 폴더를 만들고 아래 두 파일을 생성합니다. **types.ts** — API 파라미터 타입 정의: ```typescript import { CommonListParams } from '../types'; // API 파라미터 타입 (swagger의 메서드 파라미터 참고) export interface GetFilterListParams extends CommonListParams { // swagger 메서드의 query 파라미터들 } ``` > **주의**: swagger 생성 타입의 re-export는 하지 않습니다. DTO 타입이 필요한 곳에서 `@/types/data-contracts`를 직접 import합니다. **index.ts** — swagger 클라이언트를 사용하는 React Query 훅: ```typescript import { filterApi } from '@apis/swagger-client'; import { toPascalCaseKeys } from '@apis/utils/toPascalCaseKeys'; import type { FilterListData, FilterItem } from '@/types/data-contracts'; import { AxiosError } from 'axios'; import { useQuery } from 'react-query'; import type { GetFilterListParams } from './types'; // GET → useQuery 훅 export const useGetFilterListQuery = ( params: GetFilterListParams, options?: { enabled?: boolean }, ) => useQuery<FilterListData, AxiosError>({ queryKey: ['FilterList', params], queryFn: () => filterApi.filterList(toPascalCaseKeys(params)).then(res => res.data), ...options, }); // POST/PUT/DELETE → 직접 export export const PostFilterApi = async (data: FilterItem) => filterApi.filterCreate(data); ``` ### 훅 작성 규칙 - **GET 메서드** → `useQuery` 훅으로 래핑. 네이밍: `useGet{Domain}{Endpoint}Query` - **POST/PUT/DELETE 메서드** → async 함수로 직접 export. 네이밍: `Post{Domain}Api`, `Put{Domain}Api`, `Delete{Domain}Api` - **queryKey**: 도메인 + 엔드포인트를 조합한 고유 문자열 (예: `'FilterList'`) - **toPascalCaseKeys**: 목록 조회 등 query 파라미터가 있는 메서드에 적용 - **options**: `{ enabled?: boolean }` 기본 제공, 필요 시 `initialData` 등 추가 - **swagger 생성 타입(DTO)은 `@/types/data-contracts`에서 직접 import** (re-export 금지) - **파라미터 타입은 반드시 `types.ts`에 별도 정의**: 훅/API 함수의 파라미터 타입을 `index.ts`에 인라인으로 정의하지 않고, 같은 폴더의 `types.ts`에 인터페이스로 정의한 뒤 import하여 사용합니다. ```typescript // ❌ 지양: index.ts에 인라인 타입 정의 export const useGetFilterQuery = (params: { id: number; type: string }) => ... // ✅ 권장: types.ts에 별도 정의 후 import // types.ts export interface GetFilterParams { id: number; type: string; } // index.ts import type { GetFilterParams } from './types'; export const useGetFilterQuery = (params: GetFilterParams) => ... ``` ## Step 4: 수정된 API 처리 ### 4-1. 변경 내용 분석 `git diff src/types/{Modified}.ts`의 변경 내용을 분석합니다: - 메서드 추가/변경/삭제 - 파라미터 타입 변경 - 리턴 타입 변경 `git diff src/types/data-contracts.ts`도 확인하여 DTO 타입 변경 사항을 파악합니다. ### 4-2. 기존 훅 업데이트 변경된 도메인에 대응하는 `src/apis/api/{domain}/` 폴더가 있다면: - 새 메서드 추가 → 새 훅/API 함수 추가 - 메서드 시그니처 변경 → 기존 훅의 파라미터/리턴 타입 수정 - 타입 변경 → `types.ts`의 파라미터 인터페이스 수정 ### 4-3. 영향 범위 탐색 및 반영 변경된 타입이나 메서드를 사용하는 파일을 Grep으로 검색합니다: - `src/containers/` — 비즈니스 로직에서의 사용처 - `src/pages/` — 페이지 컴포넌트에서의 사용처 - `src/components/` — UI 컴포넌트에서의 사용처 타입 불일치가 발생하는 곳을 찾아 수정합니다. ## Step 5: 결과 보고 작업 완료 후 아래 항목을 정리하여 보고합니다: - **새로 생성된 파일**: 생성된 훅/타입 파일 목록 - **수정된 파일**: 변경된 파일과 변경 이유 - **수동 확인 필요**: 자동으로 처리하지 못한 항목 (있을 경우) ## 참조 파일 | 파일 | 용도 | |------|------| | `src/apis/swagger-client.ts` | API 클라이언트 팩토리 및 export | | `src/apis/api/types.ts` | CommonListParams 베이스 타입 | | `src/apis/utils/toPascalCaseKeys.ts` | camelCase→PascalCase 변환 |
이 커맨드는 Swagger와의 동기화로 변경된 API 명세를 기반으로 프론트엔드 명세에 맞는 훅을 생성&수정&삭제하고 일련의 후처리 작업을 함께 수행한다.
원한다면 동기화를 한 직후 ‘방금 업데이트된 POST API를 사용하는 곳에서, 새로 추가된 payload를 받는 입력 폼을 추가해줘’와 같이 요청해서 추가 요구사항에 대한 명세를 완벽히 작성하지 않아도 Claude Code가 API 수정 내용을 분석해 추가 요구사항을 즉각 반영할 수 있도록 유도할 수도 있다.

여담

사실, 기존 swagger 문서에는 구체적인 응답 명세가 작성되어있지 않아, 프론트엔드에서는 직접 swagger UI를 통해 api를 호출해 응답 명세를 확인하며 개발하고 있었다. 그래서 처음 라이브러리 도입을 시도했을 때, 실제 api는 배포되어 있는데 프론트엔드에서 호출 함수가 정의되어 있지 않거나, 더 이상 지원되지 않는 api를 프론트에서 정의하고 있는 경우, 그리고 동일한 api에 대한 호출함수가 여러 파일에 중복 정의되어 있는 경우(프로젝트 코드가 여러 사람의 손을 거치다보니 생긴 문제로 보인다)가 있었는데 이런 경우를 자동으로 찾아 동기화시킬 수 있어 백엔드와 프론트엔드 간의 정합성은 보장할 수 있었지만, 요청/응답 타입 명세를 동기화할 수는 없었다.
장기적인 유지보수 관점에서 생각했을 때 타입 명세까지 보장할 수 있으면 좋겠다고 생각했지만, Swagger 명세를 작성하는 건 백엔드 개발자의 몫이기 때문에 나 혼자 해결할 수 있는 문제가 아니었다. 그래서 백엔드 개발자분께 swagger-typescript-api의 도입 취지와 기대 효과에 대해 설명드리며 Swagger 응답 명세를 보강해주시길 요청드렸다. 내가 괜히 백엔드 분의 일을 늘리는 건 아닐까 걱정스러웠지만 다행히 백엔드 분도 기존 시스템의 불편에 공감해주셨고 흔쾌히 협조해주셨다. 그 결과 기존의 모든 api에 타입 명세가 추가되었고, 처음 원했던 Swagger 중심의 타입 시스템을 완성할 수 있었다.
아, 그리고 우리 프로젝트엔 한 가지 문제가 더 있었는데, 조회 API의 응답 DTO 타입에 대한 정의가 되어 있지 않은 경우가 많아서 타입스크립트가 제공하는 타입 검증 시스템을 100% 활용할 수 없는 상태였다.
swagger-typescript-api를 도입하고 Claude Code의 커스텀 커맨드 기반 자동화 프로세스를 구축한 덕분에 타입 검증 시스템의 안정성과 프론트엔드 타입 정의 로직의 일관성이 대폭 개선됐고, 이후부터는 API 변경이 생겨도 백엔드 분이 세부 명세를 정리해서 전달하지 않고 ‘swagger 동기화 해주세요’ 한 마디만으로 즉각적인 조치가 가능해졌다. 물론 프론트엔드와 백엔드 간 의사소통의 필요성이 없어진 건 아니지만, 적어도 이전보다 커뮤니케이션 부담이 확연히 줄었다.

결론

기존 프론트엔드 API 연동 방식은 백엔드와 동일한 DTO 스펙을 프론트엔드에서 다시 정의해야 하는 구조였으며, 이로 인해 개발자가 스펙을 중복 정의하거나 명세 정의 중 실수가 남을 위험이 있었다. API 변경 시마다 타입 수정과 호출 로직 보완이 수반되었고, 그 과정에서 발생한 실수가 실행 환경에서 발견되는 경우가 잦았다.
swagger-typescript-api 도입 이후, Swagger 문서를 기준으로 DTO 타입과 API 호출 코드가 자동 생성되면서 이러한 구조적인 비효율이 상당 부분 해소되었다. 프론트엔드는 더 이상 개별 명세를 수동 관리하지 않고, Swagger 동기화만으로 최신 API 스펙을 반영할 수 있게 되었다.
그 결과, 첫째, DTO 관리에 투입되던 반복 작업이 감소했다. 둘째, 백엔드와 프론트엔드 간 명세 전달 과정이 단순화되어 커뮤니케이션 비용이 절감되었다. 셋째, 타입 변경 사항이 컴파일 단계에서 즉시 검출되면서 코드 안정성이 향상되었다.