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

.prettierignore

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

eslint.config.js

@@ -10,7 +10,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

@@ -7,9 +7,11 @@
     "dev": "vite",
     "build": "tsc -b && vite build",
     "lint": "eslint .",
-    "preview": "vite preview"
+    "preview": "vite preview",
+    "gen:swagger-ts-api": "dotenv -e .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 --type-suffix DTO --axios -t ./src/shared/api/generate/templates"
   },
   "dependencies": {
+    "axios": "^1.13.2",
     "eslint-import-resolver-typescript": "^4.4.4",
     "react": "^19.2.0",
     "react-dom": "^19.2.0"
@@ -22,6 +24,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",
@@ -31,6 +35,7 @@
     "eslint-plugin-react-refresh": "^0.4.24",
     "globals": "^16.5.0",
     "prettier": "3.7.4",
+    "swagger-typescript-api": "^13.2.16",
     "typescript": "~5.9.3",
     "typescript-eslint": "^8.46.4",
     "vite": "^7.2.4"

src/shared/api/axios-instance.ts

@@ -0,0 +1,60 @@
+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") || "temp";
+    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);
+        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,40 @@
+import { isAxiosError } from "axios";
+
+import { ERROR_MESSAGE } from "@/shared/api/types/response";
+
+import type {
+  ApiErrorResponse,
+  ApiErrorCode,
+  RequiredWith,
+} from "@/shared/api/types/response";
+import type { AxiosError } from "axios";
+
+// 서버 정의 에러 타입 가드
+// 서버가 보낸 에러가 맞는지 확인하는 함수
+export const isAxiosErrorWithCustomCode = (
+  error: unknown
+): error is RequiredWith<AxiosError<ApiErrorResponse>, "response"> => {
+  return (
+    isAxiosError(error) &&
+    !!error.response &&
+    !!error.response.data &&
+    typeof error.response.data.code === "string" &&
+    error.response.data.code in ERROR_MESSAGE
+  );
+};
+
+// 공통 에러 핸들러
+export const handleApiError = (error: unknown) => {
+  if (isAxiosErrorWithCustomCode(error)) {
+    const { code } = error.response.data;
+    const message = ERROR_MESSAGE[code as ApiErrorCode];
+    console.error(message);
+    return message;
+  } else if (isAxiosError(error)) {
+    console.error("서버/네트워크 오류입니다");
+    // TODO: 에러 페이지 필요
+  } else {
+    console.error("알 수 없는 에러 발생");
+    // TODO: 에러 페이지 필요
+  }
+};

src/shared/api/generate/templates/api.ejs

@@ -0,0 +1,69 @@
+<%
+const { apiConfig, routes, utils, config } = it;
+const { info, servers, externalDocs } = apiConfig;
+const { _, require, formatDescription } = utils;
+
+const server = (servers && servers[0]) || { url: "" };
+
+const descriptionLines = _.compact([
+  `@title ${info.title || "No title"}`,
+  info.version && `@version ${info.version}`,
+  info.license && `@license ${_.compact([
+    info.license.name,
+    info.license.url && `(${info.license.url})`,
+  ]).join(" ")}`,
+  info.termsOfService && `@termsOfService ${info.termsOfService}`,
+  server.url && `@baseUrl // .env 파일을 참조해주세요`,
+  externalDocs.url && `@externalDocs ${externalDocs.url}`,
+  info.contact && `@contact ${_.compact([
+    info.contact.name,
+    info.contact.email && `<${info.contact.email}>`,
+    info.contact.url && `(${info.contact.url})`,
+  ]).join(" ")}`,
+  info.description && " ",
+  info.description && _.replace(formatDescription(info.description), /\n/g, "\n * "),
+]);
+
+%>
+
+<% if (config.httpClientType === config.constants.HTTP_CLIENT.AXIOS) { %> import type { AxiosRequestConfig, AxiosResponse } from "axios"; <% } %>
+
+<% if (descriptionLines.length) { %>
+/**
+<% descriptionLines.forEach((descriptionLine) => { %>
+* <%~ descriptionLine %>
+
+<% }) %>
+*/
+<% } %>
+export class <%~ config.apiClassName %><SecurityDataType extends unknown><% if (!config.singleHttpClient) { %> extends HttpClient<SecurityDataType> <% } %> {
+
+<% if(config.singleHttpClient) { %>
+  http: HttpClient<SecurityDataType>;
+
+  constructor (http: HttpClient<SecurityDataType>) {
+    this.http = http;
+  }
+<% } %>
+
+
+<% if (routes.outOfModule) { %>
+  <% for (const route of routes.outOfModule) { %>
+
+  <%~ includeFile('./procedure-call.ejs', { ...it, route }) %>
+
+  <% } %>
+<% } %>
+
+<% if (routes.combined) { %>
+  <% for (const { routes: combinedRoutes = [], moduleName } of routes.combined) { %>
+  <%~ moduleName %> = {
+  <% for (const route of combinedRoutes) { %>
+
+  <%~ includeFile('./procedure-call.ejs', { ...it, route }) %>
+
+  <% } %>
+  }
+  <% } %>
+<% } %>
+}

src/shared/api/generate/templates/http-client.ejs

@@ -0,0 +1,143 @@
+<%
+const { apiConfig, generateResponses, config } = it;
+%>
+
+import type { AxiosInstance, AxiosRequestConfig, HeadersDefaults, ResponseType } from "axios";
+import axios from "axios";
+
+export type QueryParamsType = Record<string | number, any>;
+
+export interface FullRequestParams extends Omit<AxiosRequestConfig, "data" | "params" | "url" | "responseType"> {
+  /** set parameter to `true` for call `securityWorker` for this request */
+  secure?: boolean;
+  /** request path */
+  path: string;
+  /** content type of request body */
+  type?: ContentType;
+  /** query params */
+  query?: QueryParamsType;
+  /** format of response (i.e. response.json() -> format: "json") */
+  format?: ResponseType;
+  /** request body */
+  body?: unknown;
+}
+
+export type RequestParams = Omit<FullRequestParams, "body" | "method" | "query" | "path">;
+
+export interface ApiConfig<SecurityDataType = unknown> extends Omit<AxiosRequestConfig, "data" | "cancelToken"> {
+  securityWorker?: (securityData: SecurityDataType | null) => Promise<AxiosRequestConfig | void> | AxiosRequestConfig | void;
+  secure?: boolean;
+  format?: ResponseType;
+}
+
+export enum ContentType {
+  Json = "application/json",
+  JsonApi = "application/vnd.api+json",
+  FormData = "multipart/form-data",
+  UrlEncoded = "application/x-www-form-urlencoded",
+  Text = "text/plain",
+}
+
+export class HttpClient<SecurityDataType = unknown> {
+    public instance: AxiosInstance;
+    private securityData: SecurityDataType | null = null;
+    private securityWorker?: ApiConfig<SecurityDataType>["securityWorker"];
+    private secure?: boolean;
+    private format?: ResponseType;
+
+    constructor({ securityWorker, secure, format, ...axiosConfig }: ApiConfig<SecurityDataType> = {}) {
+        this.instance = axios.create({ ...axiosConfig, baseURL: axiosConfig.baseURL || import.meta.env.VITE_API_URL })
+        this.secure = secure;
+        this.format = format;
+        this.securityWorker = securityWorker;
+    }
+
+    public setSecurityData = (data: SecurityDataType | null) => {
+        this.securityData = data
+    }
+
+    protected mergeRequestParams(params1: AxiosRequestConfig, params2?: AxiosRequestConfig): AxiosRequestConfig {
+      const method = params1.method || (params2 && params2.method)
+
+      return {
+        ...this.instance.defaults,
+        ...params1,
+        ...(params2 || {}),
+        headers: {
+          ...((method && this.instance.defaults.headers[method.toLowerCase() as keyof HeadersDefaults]) || {}),
+          ...(params1.headers || {}),
+          ...((params2 && params2.headers) || {}),
+        },
+      };
+    }
+
+    protected stringifyFormItem(formItem: unknown) {
+      if (typeof formItem === "object" && formItem !== null) {
+        return JSON.stringify(formItem);
+      } else {
+        return `${formItem}`;
+      }
+    }
+
+    protected createFormData(input: Record<string, unknown>): FormData {
+      if (input instanceof FormData) {
+        return input;
+      }
+      return Object.keys(input || {}).reduce((formData, key) => {
+        const property = input[key];
+        const propertyContent: any[] = (property instanceof Array) ? property : [property]
+
+        for (const formItem of propertyContent) {
+          const isFileType = formItem instanceof Blob || formItem instanceof File;
+          formData.append(
+            key,
+            isFileType ? formItem : this.stringifyFormItem(formItem)
+            );
+        }
+
+        return formData;
+      }, new FormData());
+    }
+
+    public request = async <T = any, _E = any>({
+        secure,
+        path,
+        type,
+        query,
+        format,
+        body,
+        ...params
+<% if (config.unwrapResponseData) { %>
+    }: FullRequestParams): Promise<T> => {
+<% } else { %>
+    }: FullRequestParams): Promise<T> => {
+<% } %>
+        const secureParams = ((typeof secure === 'boolean' ? secure : this.secure) && this.securityWorker && (await this.securityWorker(this.securityData))) || {};
+        const requestParams = this.mergeRequestParams(params, secureParams);
+        const responseFormat = (format || this.format) || undefined;
+
+        if (type === ContentType.FormData && body && body !== null && typeof body === "object") {
+          body = this.createFormData(body as Record<string, unknown>);
+        }
+
+        if (type === ContentType.Text && body && body !== null && typeof body !== "string") {
+          body = JSON.stringify(body);
+        }
+
+        return this.instance.request({
+            ...requestParams,
+            headers: {
+                ...(requestParams.headers || {}),
+                ...(type ? { "Content-Type": type } : {}),
+            },
+            params: query,
+            responseType: responseFormat,
+            data: body,
+            url: path,
+<% if (config.unwrapResponseData) { %>
+        }).then(response => response.data);
+<% } else { %>
+        });
+<% } %>
+    };
+}

src/shared/api/types/response.ts

@@ -0,0 +1,20 @@
+export interface ApiErrorResponse {
+  status: number;
+  code: ApiErrorCode;
+  message: string;
+}
+
+// 서버 정의 에러 (임시)
+export type ApiErrorCode =
+  | "INVALID_ACCESS_TOKEN_VALUE"
+  | "EXPIRED_ACCESS_TOKEN";
+
+export const ERROR_MESSAGE: Record<ApiErrorCode, string> = {
+  INVALID_ACCESS_TOKEN_VALUE: "액세스 토큰의 값이 올바르지 않습니다.",
+  EXPIRED_ACCESS_TOKEN: "액세스 토큰이 만료되었습니다. 재발급 받아주세요.",
+};
+
+// 옵셔널 타입을 필수로 지정
+export type RequiredWith<T, K extends keyof T> = T & {
+  [P in K]-?: T[P];
+};