[Init] swagger-typescript-api 및 axios 초기 세팅

.prettierignore

@@ -37,4 +37,9 @@ package-lock.json
 # OS
 .DS_Store
 Thumbs.db 
+
+# swagger-typescript-api templates
+src/shared/api/generate/templates/**
+*.ejs
+
 README.md

eslint.config.js

@@ -12,7 +12,16 @@ import eslintConfigPrettier from "eslint-config-prettier";
 import react from "eslint-plugin-react";
 
 export default defineConfig([
-  { ignores: ["dist", "node_modules", "build", "*.config.js", "*.config.ts"] },
+  {
+    ignores: [
+      "dist",
+      "node_modules",
+      "build",
+      "*.config.js",
+      "*.config.ts",
+      "**/*.ejs",
+    ],
+  },
 
   importPlugin.flatConfigs.recommended,
   importPlugin.flatConfigs.typescript,

package.json

@@ -10,7 +10,8 @@
     "preview": "vite preview",
     "prepare": "husky",
     "storybook": "storybook dev -p 6006",
-    "build-storybook": "storybook build"
+    "build-storybook": "storybook build",
+    "gen:swagger-ts-api": "dotenv -f .env cross-var -- swagger-typescript-api generate -p %SWAGGER_URL% -o ./src/shared/api/generate -n http-client.ts --extract-request-body --extract-response-body --axios -t ./src/shared/api/generate/templates --module-name-index 2"
   },
   "lint-staged": {
     "*.{ts,tsx,js,jsx}": [
@@ -22,6 +23,7 @@
     ]
   },
   "dependencies": {
+    "axios": "^1.13.2",
     "@tanstack/react-query": "^5.90.16",
     "@vanilla-extract/css": "^1.18.0",
     "@vanilla-extract/vite-plugin": "^5.1.4",
@@ -44,6 +46,8 @@
     "@typescript-eslint/eslint-plugin": "^8.51.0",
     "@typescript-eslint/parser": "^8.51.0",
     "@vitejs/plugin-react-swc": "^4.2.2",
+    "cross-var": "^1.1.0",
+    "dotenv-cli": "^11.0.0",
     "eslint": "^9.39.1",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.32.0",
@@ -57,7 +61,6 @@
     "lint-staged": "^16.2.7",
     "storybook": "^10.1.11",
     "prettier": "3.7.4",
-    "storybook": "^10.1.11",
     "typescript": "~5.9.3",
     "typescript-eslint": "^8.46.4",
     "vite": "^7.2.4",

src/app/App.tsx

@@ -1,14 +1,9 @@
 import { RouterProvider } from "react-router-dom";
 
-import ThemeProvider from "./providers";
 import { router } from "./routes/app-router";
 
 const App = () => {
-  return (
-    <ThemeProvider>
-      <RouterProvider router={router} />
-    </ThemeProvider>
-  );
+  return <RouterProvider router={router} />;
 };
 
 export default App;

src/app/main.tsx

@@ -2,7 +2,7 @@ import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
 
 import App from "@app/App";
-import AppProviders from "@app/providers";
+import { AppProviders } from "@app/providers";
 
 import "@app/styles/global.css";
 

src/app/providers/index.tsx

@@ -1,7 +1,22 @@
-import type { PropsWithChildren } from "react";
+import { QueryProvider } from "./query-provider";
+import ThemeProvider from "./theme-provider";
 
-import QueryProvider from "./query-provider";
+import type { ReactNode } from "react";
 
-export default function AppProviders({ children }: PropsWithChildren) {
-  return <QueryProvider>{children}</QueryProvider>;
-}
+export const AppProviders = ({
+  theme,
+  className,
+  children,
+}: {
+  children: ReactNode;
+  theme?: string;
+  className?: string;
+}) => {
+  return (
+    <QueryProvider>
+      <ThemeProvider theme={theme} className={className}>
+        {children}
+      </ThemeProvider>
+    </QueryProvider>
+  );
+};

src/app/providers/query-provider.tsx

@@ -1,17 +1,18 @@
-import type { PropsWithChildren } from "react";
-import { Suspense, lazy } from "react";
 import { QueryClientProvider } from "@tanstack/react-query";
+import { Suspense, lazy } from "react";
 
 import { queryClient } from "@/shared/api";
 
+import type { PropsWithChildren } from "react";
+
 const ReactQueryDevtools = import.meta.env.DEV
   ? lazy(async () => {
       const mod = await import("@tanstack/react-query-devtools");
       return { default: mod.ReactQueryDevtools };
     })
   : null;
 
-export default function QueryProvider({ children }: PropsWithChildren) {
+export const QueryProvider = ({ children }: PropsWithChildren) => {
   return (
     <QueryClientProvider client={queryClient}>
       {children}
@@ -23,4 +24,4 @@ export default function QueryProvider({ children }: PropsWithChildren) {
       ) : null}
     </QueryClientProvider>
   );
-}
+};

src/app/store/index.ts

@@ -1 +1 @@
-export { useAuthStore } from '@shared/model/auth';
+export { useAuthStore } from "@shared/model/auth";

src/pages/bookmark/bookmark-page.tsx

@@ -1,9 +1,9 @@
 const BookmarkPage = () => {
-    return (
-        <div>
-            <h1>Welcome to the Bookmark Page</h1>
-        </div>
-    );
+  return (
+    <div>
+      <h1>Welcome to the Bookmark Page</h1>
+    </div>
+  );
 };
 
-export { BookmarkPage };
+export { BookmarkPage };

src/pages/experience-matching/experience-matching-page.tsx

@@ -6,4 +6,4 @@ const ExperienceMatchingPage = () => {
   );
 };
 
-export { ExperienceMatchingPage };
+export { ExperienceMatchingPage };

src/pages/login/login-page.tsx

@@ -1,9 +1,9 @@
 const LoginPage = () => {
-    return (
-        <div>
-            <h1>Welcome to the Login Page</h1>
-        </div>
-    );
+  return (
+    <div>
+      <h1>Welcome to the Login Page</h1>
+    </div>
+  );
 };
 
-export { LoginPage };
+export { LoginPage };

src/pages/my-page/my-page.tsx

@@ -1,9 +1,9 @@
 const MyPage = () => {
-    return (
-        <div>
-            <h1>Welcome to the My Page</h1>
-        </div>
-    );
+  return (
+    <div>
+      <h1>Welcome to the My Page</h1>
+    </div>
+  );
 };
 
-export { MyPage };
+export { MyPage };

src/pages/onboarding/onboarding-page.tsx

@@ -1,9 +1,9 @@
 const OnboardingPage = () => {
-    return (
-        <div>
-            <h1>Welcome to the Onboarding Page</h1>
-        </div>
-    );
+  return (
+    <div>
+      <h1>Welcome to the Onboarding Page</h1>
+    </div>
+  );
 };
 
-export { OnboardingPage };
+export { OnboardingPage };

src/pages/register/register-page.tsx

@@ -1,9 +1,9 @@
 const RegisterPage = () => {
-    return (
-        <div>
-            <h1>Welcome to the Register Page</h1>
-        </div>
-    );
+  return (
+    <div>
+      <h1>Welcome to the Register Page</h1>
+    </div>
+  );
 };
 
-export { RegisterPage }; 
+export { RegisterPage };

src/shared/api/axios-instance.ts

@@ -0,0 +1,62 @@
+import axios from "axios";
+
+const SERVER_URL = import.meta.env.VITE_API_URL;
+
+// TODO: 현재는 axios로 instance를 생성하지만, http-client.ts Api 클래스로 instance를 생성하도록 수정할 예정입니다.
+export const api = axios.create({
+  baseURL: `${SERVER_URL}`,
+  headers: {
+    "Content-Type": "application/json",
+  },
+});
+
+api.interceptors.request.use(
+  async (config) => {
+    // TODO: 액세스 토큰 가져오는 로직은 utils/token로 대체 예정
+    const accessToken = localStorage.getItem("access_token") || null;
+    if (accessToken) {
+      config.headers["Authorization"] = `Bearer ${accessToken}`;
+    } else {
+      // TODO: 로그인이 필요하다는 Toast Message
+      console.error("액세스 토큰이 존재하지 않습니다");
+      window.location.replace("/login");
+      throw new Error("액세스 토큰이 존재하지 않습니다");
+    }
+    return config;
+  },
+  (error) => Promise.reject(error)
+);
+
+api.interceptors.response.use(
+  (response) => response,
+  async (error) => {
+    const originalRequest = error.config;
+
+    if (error.response?.status === 401 && !originalRequest._retry) {
+      originalRequest._retry = true;
+      try {
+        // TODO: refreshToken 관련은 차후 순위로 개발할 예정
+        // 액세스 토큰 재발급 API
+        const { data } = await axios.post("토큰 재발급 path", null, {
+          withCredentials: true, // (토큰을 cookie에 넣었을 경우 사용됨)
+        });
+
+        // 새로 발급 받은 액세스 토큰 저장
+        const newAccessToken = data.accessToken;
+        localStorage.setItem("access_token", newAccessToken);
+
+        originalRequest.headers["Authorization"] = `Bearer ${newAccessToken}`;
+        return api(originalRequest); // 이전 요청 재시도
+      } catch (refreshError) {
+        // TODO: 재발급 실패시, 로그인 화면으로 이동
+        console.error("리프레쉬 토큰 요청에 실패했습니다.", error);
+        localStorage.removeItem("access_token"); // TODO: 토큰, 유저 정보 모두 삭제
+        window.location.replace("/login");
+
+        return Promise.reject(refreshError);
+      }
+    }
+
+    return Promise.reject(error);
+  }
+);

src/shared/api/error-handler.ts

@@ -0,0 +1,55 @@
+import { isAxiosError } from "axios";
+
+import { ERROR_MESSAGE } from "@/shared/api/types/error-response";
+
+import type {
+  ApiErrorResponse,
+  ApiErrorCode,
+  RequiredWith,
+} from "@/shared/api/types/error-response";
+import type { AxiosError } from "axios";
+
+/**
+ * 서버 정의 에러(Business Error) 타입 가드
+ * - HTTP 상태 코드는 정상이지만, 비즈니스 로직상 실패한 경우를 식별합니다.
+ * - 응답 본문(data)에 'prefix' 필드가 있는지 확인합니다. (추후 TODO)
+ */
+export const isValidCustomError = (
+  error: unknown
+): error is RequiredWith<AxiosError<ApiErrorResponse>, "response"> => {
+  return (
+    isAxiosError(error) &&
+    !!error.response &&
+    !!error.response.data &&
+    typeof error.response.data.prefix === "string"
+  );
+};
+
+// 요청 종류 구분 (UI 피드백 방식을 결정하기 위함)
+type ErrorType = "query" | "mutation";
+
+/**
+ * API 공통 에러 핸들러
+ * @param error 발생한 에러 객체
+ * @param type 요청 종류 ('query': 조회 -> 에러페이지 / 'mutation': 수정 -> 토스트)
+ */
+export const handleApiError = (error: unknown, type: ErrorType) => {
+  if (isValidCustomError(error)) {
+    const { prefix } = error.response.data;
+    const message =
+      ERROR_MESSAGE[prefix as ApiErrorCode] ??
+      "알 수 없는 에러가 발생했습니다.";
+
+    console.error(message);
+    if (type == "mutation") {
+      // TODO: toast 메시지 handleApiError 내부처리 or message return 후 컴포넌트에서 처리
+      return message;
+    }
+  } else if (isAxiosError(error)) {
+    console.error("서버/네트워크 오류입니다");
+    // TODO: 에러 페이지 필요
+  } else {
+    console.error("알 수 없는 에러 발생");
+    // TODO: 에러 페이지 필요
+  }
+};