swagger-fsd-gen 1.0.2 → 1.0.3

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 1.0.3
+
+- Fixed invalid TypeScript identifiers in generated mutation keys when API paths contain `-` (for example `undo-upload`, `applied-campaigns`, `notification-settings`, `custom-filters`).
+- Added stable HTTP client selection via `--http-client <ky|axios>` (default: `ky` for backward compatibility).
+- Updated generated API templates to emit correct imports/types/calls for both `ky` and `axios`.
+- Updated TanStack mutation template to emit client-specific variable types and options (`KyInstance/Options` or `AxiosInstance/AxiosRequestConfig`).

package/README.md

@@ -1,10 +1,10 @@
 # swagger-fsd-gen
 
-Swagger/OpenAPI 문서를 기반으로 **ky + TanStack Query + FSD(Feature-Sliced Design) 패턴**에 맞는 API 클라이언트를 자동으로 생성하는 도구입니다.
+Swagger/OpenAPI 문서를 기반으로 **axios/ky + TanStack Query + FSD(Feature-Sliced Design) 패턴**에 맞는 API 클라이언트를 자동으로 생성하는 도구입니다.
 
 ## ✨ 주요 기능
 
-- 🚀 **ky HTTP 클라이언트** 기반 API 클래스 자동 생성
+- 🚀 **axios/ky HTTP 클라이언트 선택** 기반 API 클래스 자동 생성
 - 🔄 **TanStack Query** 훅 자동 생성 (useQuery, useMutation)
 - 📁 **FSD(Feature-Sliced Design)** 패턴 자동 적용
 - 🔐 **HTTP Basic Authentication** 지원
@@ -33,6 +33,12 @@ npx generate-all --uri https://api.example.com/swagger.json --username your-user
 # yarn
 yarn fetch-swagger --url https://api.example.com/swagger.json --username your-username --password your-password
 yarn generate-all --uri https://api.example.com/swagger.json --username your-username --password your-password
+
+# axios 클라이언트로 생성
+yarn generate-all --uri https://api.example.com/swagger.json --http-client axios
+
+# ky 클라이언트로 생성 (기본값)
+yarn generate-all --uri https://api.example.com/swagger.json --http-client ky
 ```
 
 ### 2. package.json에 스크립트 추가 (권장)
@@ -91,6 +97,7 @@ src/
 | --uri                  | Swagger 문서 URL/경로 | 필수                                       |
 | --username             | Basic Auth 사용자명   | -                                          |
 | --password             | Basic Auth 비밀번호   | -                                          |
+| --http-client          | HTTP 클라이언트 선택  | ky (`axios`, `ky`)                         |
 | --dto-output-path      | DTO 파일 경로         | src/shared/api/dto.ts                      |
 | --api-output-path      | API 클래스 경로       | src/entities/{moduleName}/api/index.ts     |
 | --query-output-path    | Query 훅 경로         | src/entities/{moduleName}/api/queries.ts   |

package/USAGE.md

@@ -40,6 +40,12 @@ generate-all --uri https://api.example.com/swagger.json
 # 로컬 파일에서 생성
 generate-all --uri ./swagger/my-api.yml
 
+# axios 클라이언트로 생성
+generate-all --uri ./swagger/my-api.yml --http-client axios
+
+# ky 클라이언트로 생성 (기본값)
+generate-all --uri ./swagger/my-api.yml --http-client ky
+
 # 인증이 필요한 경우
 generate-all --uri https://api.example.com/swagger.json --username admin --password secret
 ```
@@ -65,7 +71,11 @@ src/
 ### 1. 필요한 패키지 설치
 
 ```bash
+# ky를 사용할 때
 npm install ky @tanstack/react-query
+
+# axios를 사용할 때
+npm install axios @tanstack/react-query
 ```
 
 ### 2. API 인스턴스 설정

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "swagger-fsd-gen",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "main": "index.js",
-  "description": "Swagger API client generator that creates type-safe API clients using ky and TanStack Query with Feature Sliced Design pattern. Automatically generates API client code from Swagger/OpenAPI specifications.",
+  "description": "Swagger API client generator that creates type-safe API clients using axios or ky and TanStack Query with Feature Sliced Design pattern. Automatically generates API client code from Swagger/OpenAPI specifications.",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },
@@ -12,6 +12,7 @@
     "api-client",
     "typescript",
     "ky",
+    "axios",
     "tanstack-query",
     "code-generator",
     "fsd"

package/scripts/generate-all.js

@@ -2,7 +2,7 @@
 
 /**
  * Swagger API 클라이언트 자동 생성 도구
- * - ky HTTP 클라이언트 기반 API 클래스 생성
+ * - axios/ky HTTP 클라이언트 기반 API 클래스 생성
  * - TanStack Query 훅 생성 (useQuery, useMutation)
  * - FSD(Feature-Sliced Design) 패턴 적용
  */
@@ -72,6 +72,7 @@ const parseArguments = () => {
       "uri",
       "username",
       "password",
+      "http-client",
       "dto-output-path",
       "api-output-path",
       "api-instance-output-path",
@@ -83,6 +84,7 @@ const parseArguments = () => {
       u: "uri",
       un: "username",
       pw: "password",
+      hc: "http-client",
       dp: "dto-output-path",
       ap: "api-output-path",
       aip: "api-instance-output-path",
@@ -96,6 +98,7 @@ const parseArguments = () => {
     uri: argv.uri,
     username: argv.username,
     password: argv.password,
+    httpClient: argv["http-client"],
     dtoOutputPath: argv["dto-output-path"],
     apiOutputPath: argv["api-output-path"],
     apiInstanceOutputPath: argv["api-instance-output-path"],
@@ -105,6 +108,23 @@ const parseArguments = () => {
   };
 };
 
+/**
+ * HTTP 클라이언트 모드 정규화
+ * @param {string | undefined} input
+ * @returns {"axios" | "ky"}
+ */
+const resolveHttpClient = (input) => {
+  const normalized = (input ?? "ky").toString().toLowerCase();
+
+  if (normalized === "axios" || normalized === "ky") {
+    return normalized;
+  }
+
+  throw new Error(
+    `Invalid --http-client value "${input}". Supported values: axios | ky`
+  );
+};
+
 /**
  * 출력 경로 설정 (FSD 패턴 기본값)
  * @param {Object} args - 명령행 인수
@@ -172,6 +192,7 @@ const printUsage = (outputPaths) => {
   console.error(
     "Usage: generate-all --uri <swagger-url|swagger-file-name> " +
       "[--username <username>] [--password <password>] " +
+      "[--http-client <axios|ky>] " +
       "[--dto-output-path <dto-output-path>] " +
       "[--api-output-path <api-output-path>] " +
       "[--query-output-path <query-output-path>] " +
@@ -196,10 +217,12 @@ export const generateApiCode = async ({
   uri,
   username,
   password,
+  httpClient,
   templates,
   ...params
 }) => {
   const isLocal = !isUrl(uri);
+  const httpClientType = httpClient === "axios" ? "axios" : "fetch";
 
   return generateApi({
     input: isLocal ? path.resolve(process.cwd(), uri) : undefined,
@@ -226,6 +249,7 @@ export const generateApiCode = async ({
     schemaParsers: {
       complexAnyOf: AnyOfSchemaParser,
     },
+    httpClientType,
     ...params,
   });
 };
@@ -248,7 +272,7 @@ const formatWithProjectPrettier = (filePath) => {
  * @param {Object} outputPaths - 출력 경로 설정
  */
 const generateApiFunctionCode = async (args, outputPaths) => {
-  const { projectTemplate, uri, username, password } = args;
+  const { projectTemplate, uri, username, password, httpClient } = args;
 
   const templatePath = projectTemplate
     ? path.resolve(process.cwd(), projectTemplate)
@@ -260,8 +284,10 @@ const generateApiFunctionCode = async (args, outputPaths) => {
     uri,
     username,
     password,
+    httpClient,
     templates: templatePath,
-    prettier: false, // prettier 비활성화
+    // swagger-typescript-api + prettier 조합에서 parser 추론 실패를 방지
+    prettier: { parser: "typescript" },
   });
 
   for (const { fileName, fileContent } of apiFunctionCode.files) {
@@ -307,7 +333,7 @@ const generateApiFunctionCode = async (args, outputPaths) => {
  * @param {Object} outputPaths - 출력 경로 설정
  */
 const generateTanstackQueryCode = async (args, outputPaths) => {
-  const { projectTemplate, uri, username, password } = args;
+  const { projectTemplate, uri, username, password, httpClient } = args;
 
   const templatePath = projectTemplate
     ? path.resolve(process.cwd(), projectTemplate, "tanstack-query")
@@ -319,8 +345,10 @@ const generateTanstackQueryCode = async (args, outputPaths) => {
     uri,
     username,
     password,
+    httpClient,
     templates: templatePath,
-    prettier: false, // prettier 비활성화
+    // swagger-typescript-api + prettier 조합에서 parser 추론 실패를 방지
+    prettier: { parser: "typescript" },
   });
 
   for (const { fileName, fileContent } of tanstackQueryCode.files) {
@@ -369,6 +397,9 @@ const main = async () => {
   }
 
   try {
+    args.httpClient = resolveHttpClient(args.httpClient);
+    console.log(`🌐 HTTP client mode: ${args.httpClient}`);
+
     // 1. API 클래스와 DTO 생성
     await generateApiFunctionCode(args, outputPaths);
 

package/templates/api.ejs

@@ -2,13 +2,14 @@
 /**
  * API 클래스 생성 템플릿
  * - Swagger 태그별로 API 클래스 생성
- * - ky HTTP 클라이언트 기반
+ * - axios/ky HTTP 클라이언트 기반
  * - 타입 안전성을 위한 TypeScript 지원
  * - 쿼리 파라미터 처리를 위한 유틸리티 메서드 포함
  */
 
 const { utils, route, config, modelTypes } = it;
 const { _, pascalCase, require } = utils;
+const isAxios = config.httpClientType === 'axios';
 
 // 모듈명을 PascalCase로 변환하여 클래스명 생성 (예: user -> UserApi)
 const apiClassName = pascalCase(route.moduleName);
@@ -20,27 +21,32 @@ const routes = route.routes;
 const dataContracts = _.map(modelTypes, "name");
 %>
 
-import { KyInstance, Options } from 'ky';
+<% if (isAxios) { %>
+import type { AxiosInstance, AxiosRequestConfig } from 'axios';
+<% } else { %>
+import type { KyInstance, Options } from 'ky';
+<% } %>
 
 <%~ includeFile('./dto-import.ejs', { ...it }) %>
 
 /**
  * <%= route.moduleName %> 모듈 API 클래스
- * - ky HTTP 클라이언트를 사용한 API 호출
+ * - 선택된 HTTP 클라이언트를 사용한 API 호출
  * - 타입 안전성을 위한 TypeScript 지원
  * - 쿼리 파라미터 자동 변환 기능
  */
 export class <%= apiClassName %>Api {
-private readonly instance: KyInstance;
+private readonly instance: <%= isAxios ? 'AxiosInstance' : 'KyInstance' %>;
 
 /**
  * API 클래스 생성자
- * @param instance - ky HTTP 클라이언트 인스턴스
+ * @param instance - HTTP 클라이언트 인스턴스
  */
-constructor(instance: KyInstance) {
+constructor(instance: <%= isAxios ? 'AxiosInstance' : 'KyInstance' %>) {
 this.instance = instance;
 }
 
+<% if (!isAxios) { %>
 /**
  * 객체를 URLSearchParams로 변환하는 정적 유틸리티 메서드
  * - 중첩된 객체나 배열을 쿼리 파라미터로 변환
@@ -70,6 +76,7 @@ static createSearchParams(
 
   return urlSearchParams;
 }
+<% } %>
 
 <% for (const route of routes) { %>
 <%~ includeFile('./procedure-call.ejs', { ...it, route, apiClassName }) %>

package/templates/procedure-call.ejs

@@ -10,6 +10,7 @@
 const { utils, route, config, apiClassName } = it;
 const { _, pascalCase } = utils;
 const routeDocs = includeFile("./route-docs", { config, route, utils });
+const isAxios = config.httpClientType === 'axios';
 
 /**
  * API 메서드명 생성
@@ -42,6 +43,7 @@ const headerName = headers ? `${pascalCase(route.routeName.usage)}Headers` : nul
 
 // 쿼리 파라미터 타입명 생성
 const queryTypeName = query ? `${pascalCase(route.routeName.usage)}QueryParams` : null;
+const instanceParamName = isAxios ? 'axiosInstance' : 'kyInstance';
 
 /**
  * 메서드 파라미터 문자열 생성
@@ -61,20 +63,21 @@ const generateParams = (params, query, payload, headerName) => {
         ...(payload ? [`data${payload.optional ? '?' : ''}: ${payload.type}`] : [])
     ];
 
-    // ky Options에서 제외할 타입들 (중복 방지)
+    // HTTP client options에서 제외할 타입들 (중복 방지)
     const omitTypes = [
-        ...(query ? ["'searchParams'"] : []),
-        ...(payload ? ["'json'"] : []),
+        ...(query ? [isAxios ? "'params'" : "'searchParams'"] : []),
+        ...(payload ? [isAxios ? "'data'" : "'json'"] : []),
         ...(headerName ? ["'headers'"] : [])
     ];
 
-    // ky Options 타입 생성 (중복되는 속성 제외)
+    // HTTP client options 타입 생성 (중복되는 속성 제외)
+    const optionsBaseType = isAxios ? 'AxiosRequestConfig' : 'Options';
     const optionsType = omitTypes.length > 0
-            ? `Omit<Options, ${omitTypes.join(' | ')}>${headerName ? ` & { headers: ${headerName} }` : ''}`
-            : 'Options';
+            ? `Omit<${optionsBaseType}, ${omitTypes.join(' | ')}>${headerName ? ` & { headers: ${headerName} }` : ''}`
+            : optionsBaseType;
 
-    // ky 인스턴스와 옵션 파라미터 추가
-    paramList.push('kyInstance?: KyInstance', `options?: ${optionsType}`);
+    // HTTP 클라이언트 인스턴스와 옵션 파라미터 추가
+    paramList.push(`${instanceParamName}?: ${isAxios ? 'AxiosInstance' : 'KyInstance'}`, `options?: ${optionsType}`);
     return paramList.join(', ');
 };
 %>
@@ -82,14 +85,25 @@ const generateParams = (params, query, payload, headerName) => {
 /**
 <%~ routeDocs.lines %> */
 <%= functionName %>(<%~ generateParams(pathParams, query, payload, headerName) %>) {
-// ky 인스턴스 선택 (전달된 인스턴스 또는 기본 인스턴스)
-const instance = kyInstance ?? this.instance;
+// HTTP 클라이언트 인스턴스 선택 (전달된 인스턴스 또는 기본 인스턴스)
+const instance = <%= instanceParamName %> ?? this.instance;
 
-<% if (query) { %>
+<% if (query && !isAxios) { %>
     // 쿼리 파라미터를 URLSearchParams로 변환
     const urlSearchParams = <%= apiClassName %>Api.createSearchParams(params);
 <% } %>
 
+<% if (isAxios) { %>
+return instance.<%= route.request.method.toLowerCase() %><<%= responseType %>>(`<%= route.request.path.replace(/{/g, '{').replace(/}/g, '}').slice(1,) %>`, {
+<% if (query) { %>
+    params, // 쿼리 파라미터 설정
+<% } %>
+<% if (payload) { %>
+    data, // 요청 본문 설정
+<% } %>
+    ...options, // 추가 axios 옵션 병합
+}).then((response) => response.data);
+<% } else { %>
 // HTTP 요청 실행 및 JSON 응답 반환
 return instance.<%= route.request.method.toLowerCase() %><<%= responseType %>>(`<%= route.request.path.replace(/{/g, '{').replace(/}/g, '}').slice(1,) %>`,{
 <% if (query) { %>
@@ -100,4 +114,5 @@ return instance.<%= route.request.method.toLowerCase() %><<%= responseType %>>(`
 <% } %>
 ...options, // 추가 ky 옵션 병합
 }).json();
+<% } %>
 }

package/templates/route-types.ejs

@@ -4,12 +4,13 @@ const { _, pascalCase, require } = utils;
 const apiClassName = pascalCase(route.moduleName);
 const routes = route.routes;
 const dataContracts = _.map(modelTypes, "name");
+const isAxios = config.httpClientType === 'axios';
 %>
 
-import { kyInstance } from "@/shared/api"
+import { <%= isAxios ? 'axiosInstance' : 'kyInstance' %> } from "@/shared/api"
 
 import { <%= apiClassName %>Api } from './index'
 
-const <%= route.moduleName %>Api = new <%= apiClassName %>Api(kyInstance);
+const <%= route.moduleName %>Api = new <%= apiClassName %>Api(<%= isAxios ? 'axiosInstance' : 'kyInstance' %>);
 
 export { <%= route.moduleName %>Api };

package/templates/tanstack-query/route-types.ejs

@@ -6,6 +6,10 @@
 const { utils, route, modelTypes, config } = it;
 const { pascalCase, internalCase: camelCase } = utils;
 const { moduleName, routes } = route;
+const isAxios = config.httpClientType === 'axios';
+const clientInstanceParam = isAxios ? 'axiosInstance' : 'kyInstance';
+const clientInstanceType = isAxios ? 'AxiosInstance' : 'KyInstance';
+const clientOptionsType = isAxios ? 'AxiosRequestConfig' : 'Options';
 
 const getFunctionName = ({ request: { method, path } }) =>
         `${method}${pascalCase(path
@@ -18,6 +22,12 @@ const getFunctionName = ({ request: { method, path } }) =>
                 .join('_'))}`;
 
 const removeBracket = (type) => type.replace(/[()]/g, '')
+const sanitizeIdentifierSegment = (segment) =>
+        segment
+                .replace(/[${}]/g, '')
+                .replace(/[^a-zA-Z0-9]/g, '_')
+                .replace(/_+/g, '_')
+                .replace(/^_+|_+$/g, '');
 
 const getRequestParams = ({ parameters = [], query, payload, routeName }) => {
     const queryParamsDto = query ? `${pascalCase(routeName.usage)}QueryParams` : '';
@@ -40,10 +50,9 @@ const buildMutationKeyName = ({ path, method }) =>
                .split('/')
                .filter(segment => segment )
                .map(segment =>
-                       segment.match(/\${/)
-                               ? segment.replace(/[${}]/g, '').toUpperCase()
-                               : segment.toUpperCase()
+                       sanitizeIdentifierSegment(segment).toUpperCase()
                )
+               .filter(Boolean)
                .join('_')
 
 const buildPathMutationKey = ({ path }) =>
@@ -84,7 +93,7 @@ if (mutationConfigs.length > 0) {
             .filter(config => config.hasVariables)
             .map(config => {
                 const headerName = config.route.specificArgs.headers ? `${pascalCase(config.route.routeName.usage)}Headers` : null;
-                return `type T${pascalCase(config.functionName)}Variables = { ${config.requestParams}, kyInstance?: KyInstance; options?: ${headerName ? `Omit<Options, 'headers'> & { headers: ${headerName} }` : 'Options'}; };`
+                return `type T${pascalCase(config.functionName)}Variables = { ${config.requestParams}, ${clientInstanceParam}?: ${clientInstanceType}; options?: ${headerName ? `Omit<${clientOptionsType}, 'headers'> & { headers: ${headerName} }` : clientOptionsType}; };`
             })
             .join('\n');
 
@@ -98,7 +107,11 @@ UseMutationOptions,
 useQueryClient,
 } from '@tanstack/react-query';
 import { useMutation } from '@tanstack/react-query';
+<% if (isAxios) { %>
+import type{ AxiosInstance, AxiosRequestConfig } from 'axios';
+<% } else { %>
 import type{ KyInstance, Options } from 'ky';
+<% } %>
 
 <%~ includeFile('../dto-import.ejs', { ...it }) %>
 
@@ -114,8 +127,8 @@ const mutations = {
 <% for (const config of mutationConfigs) { %>
     <%= config.functionName %>: () => ({
     mutationFn: <% if (config.hasVariables) { %>(variables: T<%= pascalCase(config.functionName) %>Variables) => {
-    const { <%= config.requestParamsWithoutTypes %>, kyInstance, options } = variables;
-    return <%= moduleName %>Api.<%= config.functionName %>(<%= config.requestParamsWithoutTypes %>, kyInstance, options);
+    const { <%= config.requestParamsWithoutTypes %>, <%= clientInstanceParam %>, options } = variables;
+    return <%= moduleName %>Api.<%= config.functionName %>(<%= config.requestParamsWithoutTypes %>, <%= clientInstanceParam %>, options);
     }<% } else { %>() => <%= moduleName %>Api.<%= config.functionName %>()<% } %>,
     mutationKey: <% ~moduleName.toUpperCase() %>_MUTATION_KEY.<% ~config.mutationKeyName %>,
     }),