[ADD/#110] scripts / generate-api 스크립트 세팅

[ahcgnoej]

개요

API 연동 작업을 할 때마다 반복되는 보일러플레이트를 없애기 위해 generate-api 스크립트를 도입했습니다.

기존에는 orval을 직접 실행하면 OpenAPI 스펙 전체(API 200개+, DTO 200개+)가 한꺼번에 생성되어 필요 없는 파일이 쏟아지는 문제가 있었습니다. 또한 파일을 생성한 이후에도 shared/api/index.ts에 export를 수동으로 등록하고, feature 레이어에 React Query 훅 파일을 직접 작성해야 하는 반복 작업이 남아 있었습니다.

이 스크립트는 "필요한 API 하나만 골라 전체 과정을 자동화" 하는 것을 목표로 만들었습니다.

---

왜 만들었나요?

기존 방식	이 스크립트
orval 실행 → 전체 스펙 생성 (수백 개)	지정한 operationId만 미니 스펙으로 추출 후 생성
index.ts에 export 수동 등록	자동 등록 (중복 방지 포함)
React Query 훅 파일 직접 작성	HTTP 메서드 감지 후 자동 생성
feature 폴더 직접 지정	대화형으로 선택 가능

---

사용 방법

자세한 내용은 scripts/generate-api.md 를 참고하세요.

1. 사용 가능한 API 목록 확인

yarn generate:api --list

checkPhoneAvailabilityAndSendAuthNumber    POST /auth/phone-verification/check-and-send
ssuAuth                                   POST /auth/students/ssu-verify
signupStudent                             POST /auth/students/signup
getNotices                                GET  /notices
...

2. API 연동 (한 번에 전부 자동 처리)

yarn generate:api --operations <operationId>

--feature 없이 실행하면 feature 폴더를 대화형으로 선택할 수 있습니다.

❓ --feature 가 없습니다. 어느 feature에 훅을 생성할까요?

   1. inquiry-form
   2. partnership-contract
   3. signup-user-flow
   ...
   
선택 (1-N):

또는 --feature를 직접 지정할 수도 있습니다.

yarn generate:api --operations getNotices --feature notice

여러 개를 한 번에 생성할 때는 콤마로 구분합니다.

yarn generate:api --operations getNotices,createNotice --feature notice

3. 자동으로 처리되는 것

1. src/shared/api/_generated/auth/.ts ← 생성 (수정 금지)

/**
 * Generated by orval v7.13.2 🍺
 * Do not edit manually.
 * ASSU API
 * ASSU API 명세서
 * OpenAPI spec version: 1.0.0
 */
import { customInstance } from "../../orvalMutator";
/**
 * 휴대폰 번호 중복가입 확인 및 인증번호 발송 요청
 */
export interface PhoneAuthSendRequestDTO {
	/**
	 * 인증번호를 받을 휴대폰 번호
	 * @pattern ^010\d{8}$
	 */
	phoneNumber: string;
}

export type BaseResponseVoidResult = { [key: string]: unknown };

export interface BaseResponseVoid {
	isSuccess?: boolean;
	code?: string;
	message?: string;
	result?: BaseResponseVoidResult;
}

export const getAssuApi = () => {
	/**
 * # [v1.1 (2025-09-25)](https://clumsy-seeder-416.notion.site/2241197c19ed801bbcd9f61c3e5f5457?source=copy_link)
- 입력한 휴대폰 번호로 1회용 인증번호(OTP)를 발송합니다.
- 중복된 전화번호가 있으면 에러를 반환합니다.
- 관리자와 제휴업체의 회원가입 이전에 사용하여 전화번호를 검증합니다.
- 유효시간/재요청 제한 정책은 서버 설정에 따릅니다.

**Request Body:**
  - `phoneNumber` (String, required): 인증번호를 받을 휴대폰 번호

**Response:**
  - 성공 시 200(OK)과 성공 메시지 반환
 * @summary 휴대폰 번호 중복가입 확인 및 인증번호 발송 API
 */
	const checkPhoneAvailabilityAndSendAuthNumber = (
		phoneAuthSendRequestDTO: PhoneAuthSendRequestDTO,
	) => {
		return customInstance<BaseResponseVoid>({
			url: `/auth/phone-verification/check-and-send`,
			method: "POST",
			headers: { "Content-Type": "application/json" },
			data: phoneAuthSendRequestDTO,
		});
	};

	return { checkPhoneAvailabilityAndSendAuthNumber };
};
export type CheckPhoneAvailabilityAndSendAuthNumberResult = NonNullable<
	Awaited<
		ReturnType<
			ReturnType<typeof getAssuApi>["checkPhoneAvailabilityAndSendAuthNumber"]
		>
	>
>;

2. src/shared/api/index.ts ← export 자동 등록

import "./interceptors";

export type { ApiError, ApiResponse } from "@/shared/types/api";
export type {
	BaseResponseVoid,
	PhoneAuthSendRequestDTO,
} from "./_generated/auth/checkPhoneAvailabilityAndSendAuthNumber";

// checkPhoneAvailabilityAndSendAuthNumber
export { getAssuApi as getCheckPhoneAvailabilityAndSendAuthNumberApi } from "./_generated/auth/checkPhoneAvailabilityAndSendAuthNumber";
export { apiInstance } from "./instance";

3. src/features//api/useMutation.ts ← 훅 자동 생성
   또는 useQuery.ts (GET이면)

   import { useMutation } from "@tanstack/react-query";
import { getCheckPhoneAvailabilityAndSendAuthNumberApi } from "@/shared/api";

const { checkPhoneAvailabilityAndSendAuthNumber } =
	getCheckPhoneAvailabilityAndSendAuthNumberApi();

export function useCheckPhoneAvailabilityAndSendAuthNumberMutation() {
	return useMutation({ mutationFn: checkPhoneAvailabilityAndSendAuthNumber });
}

4. 생성된 훅 바로 사용

import { useGetNoticesQuery } from "@/features/notice/api/useGetNoticesQuery";

const { data, isLoading } = useGetNoticesQuery();

---

주요 기능

• HTTP 메서드 자동 감지: GET → useQuery, POST/PUT/DELETE → useMutation

• GET 파라미터 자동 파싱: 함수 시그니처를 읽어 파라미터가 있으면 훅에 자동 반영

  // 파라미터가 있는 GET API라면 이렇게 생성됨
  export function useGetNoticesQuery(params: GetNoticesParams) {
    return useQuery({
      queryKey: ["getNotices", params],
      queryFn: () => getNotices(params),
    });
  }

• DTO 중복 export 방지: 여러 API가 공통 DTO를 참조해도 index.ts에 중복 등록 없음

• 에러 격리: 여러 operationId를 한 번에 생성할 때 하나가 실패해도 나머지는 계속 진행

• 임시 파일 자동 정리: 에러 발생 시에도 .orval.tmp.* 파일 반드시 삭제

---

참고 파일

파일	설명
scripts/generate-api.js	스크립트 본체
scripts/generate-api.md	사용법 및 내부 함수 상세 설명
src/shared/api/index.ts	Public API — 스크립트가 자동 등록
src/shared/api/_generated/	자동생성 파일 — 수정 금지
src/shared/api/orvalMutator.ts	orval ↔ axios 인스턴스 연결

---

관련 이슈

close #110

리뷰어에게

자동 (스크립트가 처리)

• _generated/auth/.ts 생성
• shared/api/index.ts export 등록
• features//api/useMutation.ts 훅 파일 생성

수동 (직접 해야 함)

• 컨트롤러/화면에서 훅 import해서 사용
• 비즈니스 로직 작성 (성공/실패 처리, UI 연동 등)

해당 스크립트는 자유롭게 개선해주셔도 되고 의견주셔도 됩니다. 단순작업은 자동화 시키면 좋을 것 같아 진행했습니다 (+ 오타방지 및 나중 백엔드 스펙 변경 시 스크립트로 자동반영될수있게)
폴더 구조나 컨벤션 수정도 더 가능할 것 같고, 해당 브랜치에서 직접 실행해서 개선시킬 부분이 있는지 확인해보셔도 좋을 것 같습니다!
자동화는 제안이라, 필요없을 것 같다면 폐기해도되니 편히 의견주세요!

[github-actions]

Thanks for the contribution!
I have applied any labels matching special text in your title and description.

Please review the labels and make any necessary changes.

[gemini-code-assist]

Code Review

This pull request introduces a new script, generate-api.js, along with a corresponding package.json command and documentation. The script automates the generation of API clients and React Query hooks by filtering the OpenAPI specification to include only specific operations, thereby reducing the size of generated code. Several critical issues were identified in the script's logic: the regex used to parse generated files is fragile and likely to fail with standard Orval output, a destructuring error leads to undefined variables, and the export name is incorrectly hardcoded. Additionally, improvements were suggested to handle missing files gracefully and to derive parameter types directly from the OpenAPI spec rather than using regex on generated code.

[eunhyekimyeah]

정말 수고하셨습니다. 채정님 덕분에 업무 속도가 훨씬 단축되겠네요 감사해요

[eunhyekimyeah]

모든 API가 도메인에 관계없이 _generated/auth/에 자동생성이 되는 것으로 파악했습니다. 기능 동작에는 문제없지만, 파일이 쌓일수록 _generated/ 폴더에서 어떤 도메인 API가 생성돼 있는지 파악하기 어려워진다는 점이 우려됩니다.

그래서 openapi.json에 각 API 마다 도메인 태그가 명시돼 있으니 이 태그를 읽어서 출력 경로를 자동으로 결정하게 하는 부분을 추가로 넣었으면 좋겠습니다. 해당 파일에 tags 정보기반 도메인 추론 함수 추가와 하드코딩된 부분이 수정되면 더 좋을 거 같아요!

[ahcgnoej]

@eunhyekimyeah 넵 일단 스웨거 도메인 태그대로, auth 폴더 안에 관련 파일 들어가는거처럼 자동으로 map, review, certification, auth, report, deviceToken, amember, partner, student, notification 이런식으로 폴더가 자동생성되어 들어가긴 할거예요!

[eunhyekimyeah]

@ahcgnoej 재민님 리뷰에서도 언급하셨는데 다 auth폴더에 생성되더라구요...!

[chunjaemin]

자동화 스크립트 좋은 것 같아요..! 이것저것 고려하시려면 오래걸리셨을텐데 고생하셨습니다

당장엔 해보니까 버그가 좀 있어서 수정해야할 것 같긴합니다..! 버그 몇개 잡고나면 자동화 되서 편리할 것 같아요 bbbbbb

건의 사항)

1. AI가 API연동시에 스크립트를 실행시키도록 하면 좋을 것 같아서 Claude.md에 명시해두면 좋지 않을까 싶네욥

2. 각 엔드포인트별 ID의 이름에 규칙이 따로 없는것으로 확인했는데 네이밍 규칙을 따로 정해두어야 나중에 ID가 겹치는 문제를 막을 수 있지 않을까 싶어욥 (ID 이름이 안이뻐용..)

3. 스크립트 재실행할 경우 훅은 덮어씌우지 않도록 되어있던데 덮어씌우는게 낫지 않을까 싶네요(?) 여러상황이 있을 것 같아 뭐가 정답인지는 잘 모르겠는데 어차피 백엔드 스펙 바뀔 때 스크립트 재실행해서 싹다 바꿔야한다고 생각하면 전부 덮어씌우는게 낫지않을까 단편적으로 한번 생각해봤습니당

버그 발견1)

1. openapi.json에 "JWT TOKEN"부분에 띄어쓰기가 되어있어서 다음과 같이 에러가 나오더라구요! (JWT TOKEN => JWT_TOKEN으로 변경해야해요)
2. JWT TOKEN의 필드에 name이 있어서 에러가나요 name필드를 제거해야한다고 하네욥
   => openapi 3.0 기준으로 허용안되는 기준인데 백엔드 api스펙에 적혀있어서 발생한 문제라고 하네요.. 추후에 백엔드 분들에게 수정 요구해야할 것 같아요

버그 발견2)

정규식에 문제가 있어서 패칭함수를 만든 뒤 useQuery로 변환할 때 올바르게 매핑하지 못하네욥

버그상세

  스크립트가 하려던 것:
  생성된 파일을 읽어서 함수에 파라미터가 있는지 감지하고, 결과에 따라 훅 템플릿을 다르게 만듭니다.

  파라미터 있음 감지 → queryFn: () => list(params)   ← 올바른 템플릿
  파라미터 없음 감지 → queryFn: list                 ← 잘못 생성됨 ❌

  왜 잘못 감지했냐면:
  
  스크립트가 파라미터를 찾는 방식:
  "const list = (params: " 이런 패턴을 찾아라

  실제 생성된 코드:
  const list = (
      params?: ListParams,   ← "?" 때문에 패턴 불일치

  params: 이어야 하는데 params?: 라서 찾기 실패 → "파라미터 없음"으로 오판

버그 발견 (?)

자동화스크립트로 생성하면 도메인에 관계없이 모두 _generated/auth/~ 에 생성하더라구요 (모두 auth 하위에 생성되도록 코드짜여있음) 각도메인별로 다른 폴더에 생성되어야 할 것 같은데 버그인지 의도한바가 있는지 궁금합니다!