swgto-ts 0.1.0 → 2.0.0

package/README.md

@@ -1,86 +1,147 @@
-# swgto
-
-`swgto` 是一个把 `OpenAPI 3.x` 文档转换成项目内请求函数的 Node.js 库和 CLI。
-
-安装后会注册一个 `swgto` 命令。执行时它会在当前目录查找 `.swaggerts.config.ts` 或 `.swaggerts.config.js`，然后生成：
-
-- 按路径前缀分组的请求文件
-- 按文档模块输出请求文件。单文档默认输出到 `services/`，多文档时多个模块目录平级
-- `outputDir/index.ts` 或 `outputDir/index.js`
-- 聚合声明文件 `outputDir/api.d.ts`
-- 类型文件 `outputDir/types.ts` 或带 JSDoc 的 `outputDir/types.js`
-
-## 安装
-
-```bash
-npm install swgto
-```
-
-## 配置
-
-在项目根目录创建 `.swaggerts.config.ts`：
-
-```ts
-import type { SwaggerTsConfig } from 'swgto';
-
-const config: SwaggerTsConfig = {
-  docUrls: 'https://example.com/openapi.json',
-  httpClientPath: '@/utils/request',
-  outputDir: 'src/api',
-  outputType: 'ts',
-  typeName: 'types',
-  cleanOutput: true,
-  renameMethod: (apiPath, method) => `${method}_${apiPath.replace(/[\\/{}]/g, '_')}`,
-  resolveRequestPath: (apiPath, method) => `/proxy${apiPath}`,
-};
-
-export default config;
-```
-
-多文档模式下需要提供 `moduleName`：
-
-```ts
-export default {
-  docUrls: [
-    'https://example.com/user-openapi.json',
-    'https://example.com/order-openapi.json',
-  ],
-  httpClientPath: '@/utils/request',
-  outputDir: 'src/api',
-  moduleName: (docUrl) => docUrl.includes('user') ? 'user' : 'order',
-};
-```
-
-## 使用
-
-```bash
-swgto
-```
-
-## 输出示例
-
-```text
-src/api/
-  api.d.ts
-  index.ts
-  types.ts
-  services/
-    get_user_list.ts
-    post_user_create.ts
-```
-
-## 配置项
-
-```ts
-export interface SwaggerTsConfig {
-  docUrls: string | string[];
-  httpClientPath: string;
-  renameMethod?: (path: string, method: string) => string;
-  resolveRequestPath?: (path: string, method: string, docUrl: string) => string;
-  outputDir?: string;
-  moduleName?: (docUrl: string) => string;
-  outputType?: 'ts' | 'js';
-  typeName?: string;
-  cleanOutput?: boolean;
-}
-```
+# swgto
+
+`swgto` 是一个把 `OpenAPI 3.x` 文档转换成项目内请求函数的 Node.js 库和 CLI。
+
+安装后会注册一个 `swgto` 命令。执行时它会在当前目录查找 `.swaggerts.config.ts` 或 `.swaggerts.config.js`，然后生成：
+
+- 按路径前缀分组的请求文件
+- 按文档模块输出请求文件。单文档默认输出到 `services/`，多文档时多个模块目录平级
+- `outputDir/index.ts` 或 `outputDir/index.js`
+- 类型文件 `outputDir/types.ts` 或带 JSDoc 的 `outputDir/types.js`
+
+## 安装
+
+```bash
+npm install swgto-ts
+```
+
+## 配置
+
+在项目根目录创建 `.swaggerts.config.ts`：
+
+```ts
+import type { SwaggerTsConfig } from 'swgto-ts'
+
+const config: SwaggerTsConfig = {
+  docUrls: 'https://example.com/openapi.json',
+  httpClientPath: '@/utils/request',
+  outputDir: 'src/api',
+  outputType: 'ts',
+  typeName: 'types',
+  cleanOutput: true,
+  renameMethod: (apiPath, method) => `${method}_${apiPath.replace(/[\\/{}]/g, '_')}`,
+  resolveRequestPath: (apiPath, method) => `/proxy${apiPath}`,
+}
+
+export default config
+```
+
+多文档模式下需要提供 `moduleName`：
+
+```ts
+export default {
+  docUrls: ['https://example.com/user-openapi.json', 'https://example.com/order-openapi.json'],
+  httpClientPath: '@/utils/request',
+  outputDir: 'src/api',
+  moduleName: (docUrl) => (docUrl.includes('user') ? 'user' : 'order'),
+}
+```
+
+## 使用
+
+```bash
+swgto
+```
+
+## 输出示例
+
+```text
+src/api/
+  index.ts
+  types.ts
+  services/
+    get_user_list.ts
+    post_user_create.ts
+```
+
+## 配置项
+
+```ts
+export interface SwaggerTsConfig {
+  docUrls: string | string[]
+  httpClientPath: string
+  renameMethod?: (path: string, method: string) => string
+  resolveRequestPath?: (path: string, method: string, docUrl: string) => string
+  ignoreUrl?: (path: string, method: string, docUrl: string) => boolean
+  outputDir?: string
+  moduleName?: (docUrl: string) => string
+  outputType?: 'ts' | 'js'
+  typeName?: string
+  cleanOutput?: boolean
+  fileNaming?: 'module' | 'path'
+  flattenQueryParam?: boolean
+  mergeParams?: boolean
+}
+```
+
+### 字段说明
+
+| 字段                 | 类型                                | 默认值       | 说明                                                                                                                                   |
+| -------------------- | ----------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `docUrls`            | `string \| string[]`                | (必填)       | OpenAPI 3.x 文档的 URL，支持单文档字符串或多文档数组                                                                                   |
+| `httpClientPath`     | `string`                            | (必填)       | 项目内 HTTP 请求工具的引入路径，生成的文件会从中 `import request`                                                                      |
+| `outputDir`          | `string`                            | `'src/api'`  | 代码输出目录，相对项目根目录                                                                                                           |
+| `outputType`         | `'ts' \| 'js'`                      | `'ts'`       | 输出文件类型，`'ts'` 生成 `.ts` 文件，`'js'` 生成 `.js` 文件（带 JSDoc 类型注释）                                                      |
+| `typeName`           | `string`                            | `'types'`    | 类型文件名（不含后缀），如 `'types'` 生成 `types.ts` 或 `types.js`                                                                     |
+| `fileNaming`         | `'module' \| 'path'`                | `'path'`     | 文件组织方式：`'path'` 按接口路径每个文件一个函数；`'module'` 按控制器合并到同一个文件                                                 |
+| `moduleName`         | `(docUrl) => string`                | `'services'` | 多文档时，为每个文档指定模块目录名。多文档模式下**必填**                                                                               |
+| `renameMethod`       | `(path, method) => string`          | 见说明       | 自定义函数名生成规则。默认根据路径和方法名自动生成（如 `get_user_list`）                                                               |
+| `resolveRequestPath` | `(path, method, docUrl) => string`  | 原路径       | 自定义请求路径转换规则，可用于添加统一前缀等，如 `(path) => \`/proxy\${path}\``                                                        |
+| `ignoreUrl`          | `(path, method, docUrl) => boolean` | 不过滤       | 过滤不需要生成代码的接口，返回 `true` 跳过当前接口                                                                                     |
+| `cleanOutput`        | `boolean`                           | `false`      | 生成前是否清空输出目录                                                                                                                 |
+| `flattenQueryParam`  | `boolean`                           | `false`      | 当 query 参数只有一个且为 `$ref` 引用类型时，直接用引用类型代替 `{ query: RefType }`                                                   |
+| `mergeParams`        | `boolean`                           | `false`      | 合并参数层级：`true` 时展平 `path/query/body` 嵌套，直接使用 `params: { field1, field2 }` 代替 `params: { path: {...}, query: {...} }` |
+
+### 函数名生成规则
+
+默认函数名格式为 `{method}_{path_segments}`，如：
+
+- `GET /user/list` → `get_user_list`
+- `POST /user/create` → `post_user_create`
+
+可通过 `renameMethod` 自定义：
+
+```ts
+renameMethod: (path, method) => `${method}_${path.replace(/[\\/{}]/g, '_')}`,
+```
+
+### 文件组织方式
+
+**`fileNaming: 'path'`（默认）**— 每个接口生成独立文件：
+
+```
+src/api/moduleA/
+  get_user_list.ts
+  post_user_create.ts
+  get_user_detail.ts
+```
+
+**`fileNaming: 'module'`**— 按控制器合并文件（自动识别 RESTful 资源路径分组）：
+
+```
+src/api/moduleA/
+  user.ts         // 包含 get_user_list, post_user_create, get_user_detail
+  order.ts        // 包含 get_order_list, post_order_create
+```
+
+### 参数合并模式
+
+`mergeParams: true` 时展平参数层级，适用于不想嵌套 `path/query/body` 的场景：
+
+```ts
+// mergeParams: false（默认），参数按来源嵌套
+getUser({ path: { id: '1' }, query: { name: 'foo' } })
+
+// mergeParams: true，参数展平
+getUser({ id: '1', name: 'foo' })
+```

package/dist/{chunk-RRFCLHNU.js → chunk-4OK6R2K5.js}

@@ -39,7 +39,10 @@ async function loadConfig(cwd) {
     outputDir: rawConfig.outputDir ?? "src/api",
     outputType: rawConfig.outputType ?? "ts",
     typeName: rawConfig.typeName ?? "types",
-    cleanOutput: rawConfig.cleanOutput ?? false
+    cleanOutput: rawConfig.cleanOutput ?? false,
+    fileNaming: rawConfig.fileNaming ?? "path",
+    flattenQueryParam: rawConfig.flattenQueryParam ?? false,
+    mergeParams: rawConfig.mergeParams ?? false
   };
   return { configPath, config };
 }
@@ -53,6 +56,152 @@ function groupByPrefix(operations) {
   }, {});
 }
 
+// src/core/groupByController.ts
+function isPathParam(segment) {
+  return segment.startsWith("{") && segment.endsWith("}");
+}
+function resultName(segments, childIndex) {
+  if (childIndex >= 2) {
+    return segments[childIndex - 1] + "_" + segments[childIndex];
+  }
+  return segments[childIndex];
+}
+function getPathMethods(operations) {
+  const map = /* @__PURE__ */ new Map();
+  for (const op of operations) {
+    if (!map.has(op.path)) map.set(op.path, /* @__PURE__ */ new Set());
+    map.get(op.path).add(op.method);
+  }
+  return map;
+}
+function deriveControllerName(path4, allPaths, pathMethods) {
+  const segments = path4.split("/").filter(Boolean);
+  if (segments.length === 0) return "index";
+  if (segments.length === 1) return segments[0];
+  let effectiveLen = segments.length;
+  while (effectiveLen > 1 && isPathParam(segments[effectiveLen - 1])) {
+    effectiveLen--;
+  }
+  if (effectiveLen === 1) return segments[0];
+  for (let depth = effectiveLen - 1; depth >= 0; depth--) {
+    const ancestorPath = "/" + segments.slice(0, depth).join("/");
+    const ancestorMethods = pathMethods.get(ancestorPath);
+    if (ancestorMethods && ancestorMethods.size > 1 && depth >= 1) {
+      return segments[depth - 1];
+    }
+    if (depth >= 1) {
+      if (allPaths.has(ancestorPath)) {
+        const ancestorController = deriveControllerName(ancestorPath, allPaths, pathMethods);
+        if (ancestorController !== segments[depth - 1]) {
+          return ancestorController;
+        }
+        return segments[depth - 1];
+      }
+      const hasDirectSibling = [...allPaths].some((p) => {
+        if (p === path4) return false;
+        if (!p.startsWith(ancestorPath + "/")) return false;
+        const remaining = p.slice(ancestorPath.length + 1);
+        return !remaining.includes("/");
+      });
+      if (hasDirectSibling) {
+        const siblingIsRest = [...allPaths].some((p) => {
+          if (p === path4) return false;
+          if (!p.startsWith(ancestorPath + "/")) return false;
+          const remaining = p.slice(ancestorPath.length + 1);
+          if (remaining.includes("/")) return false;
+          const methods = pathMethods.get(p);
+          return methods != null && methods.size > 1;
+        });
+        if (siblingIsRest) {
+          return resultName(segments, depth);
+        }
+        return segments[depth - 1];
+      }
+    }
+    const currentPath = "/" + segments.slice(0, depth + 1).join("/");
+    const hasChildren = [...allPaths].some(
+      (p) => p !== path4 && p.startsWith(currentPath + "/")
+    );
+    if (hasChildren) {
+      return resultName(segments, depth);
+    }
+  }
+  for (let i = segments.length - 1; i >= 0; i--) {
+    if (!isPathParam(segments[i])) return resultName(segments, i);
+  }
+  return segments[segments.length - 1];
+}
+function groupByController(operations) {
+  const allPaths = new Set(operations.map((op) => op.path));
+  const pathMethods = getPathMethods(operations);
+  return operations.reduce((acc, operation) => {
+    const controllerName = deriveControllerName(operation.path, allPaths, pathMethods);
+    acc[controllerName] ??= [];
+    acc[controllerName].push(operation);
+    return acc;
+  }, {});
+}
+
+// src/generators/schemaToTs.ts
+function formatPropertyName(name) {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name);
+}
+function refToTypeName(ref) {
+  const parts = ref.split("/");
+  return parts[parts.length - 1] || "unknown";
+}
+function schemaToTs(schema) {
+  if (!schema) {
+    return "unknown";
+  }
+  if (schema.$ref) {
+    return refToTypeName(schema.$ref);
+  }
+  if (schema.enum?.length) {
+    return schema.enum.map((item) => JSON.stringify(item)).join(" | ");
+  }
+  if (schema.anyOf?.length) {
+    return schema.anyOf.map((item) => schemaToTs(item)).join(" | ");
+  }
+  if (schema.oneOf?.length) {
+    return schema.oneOf.map((item) => schemaToTs(item)).join(" | ");
+  }
+  if (schema.allOf?.length) {
+    return schema.allOf.map((item) => schemaToTs(item)).join(" & ");
+  }
+  if (schema.type === "array") {
+    return `${schemaToTs(schema.items)}[]`;
+  }
+  if (schema.type === "object" || schema.properties) {
+    const requiredSet = new Set(schema.required ?? []);
+    const properties = Object.entries(schema.properties ?? {}).map(([key, value]) => {
+      const optional = requiredSet.has(key) ? "" : "?";
+      return `${formatPropertyName(key)}${optional}: ${schemaToTs(value)};`;
+    });
+    if (!properties.length && schema.additionalProperties) {
+      const valueType = schema.additionalProperties === true ? "unknown" : schemaToTs(schema.additionalProperties);
+      return `{ [key: string]: ${valueType} }`;
+    }
+    return `{ ${properties.join(" ")} }`;
+  }
+  switch (schema.type) {
+    case "integer":
+    case "number":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "string":
+      return "string";
+    case "null":
+      return "null";
+    default:
+      return "unknown";
+  }
+}
+function toTypePropertyName(name) {
+  return formatPropertyName(name);
+}
+
 // src/utils/naming.ts
 function toPascalCase(value) {
   return value.split(/[^a-zA-Z0-9]+/).filter(Boolean).map((segment) => segment[0].toUpperCase() + segment.slice(1)).join("");
@@ -77,6 +226,36 @@ function buildTypeName(functionName, suffix) {
 
 // src/core/parsePaths.ts
 var HTTP_METHODS = ["get", "post", "put", "patch", "delete", "options", "head"];
+function collectReferencedTypeNames(schema, collected = /* @__PURE__ */ new Set()) {
+  if (!schema) {
+    return [...collected];
+  }
+  if (schema.$ref) {
+    const typeName = schema.$ref.split("/").pop();
+    if (typeName) {
+      collected.add(typeName);
+    }
+  }
+  for (const child of schema.anyOf ?? []) {
+    collectReferencedTypeNames(child, collected);
+  }
+  for (const child of schema.oneOf ?? []) {
+    collectReferencedTypeNames(child, collected);
+  }
+  for (const child of schema.allOf ?? []) {
+    collectReferencedTypeNames(child, collected);
+  }
+  if (schema.items) {
+    collectReferencedTypeNames(schema.items, collected);
+  }
+  for (const property of Object.values(schema.properties ?? {})) {
+    collectReferencedTypeNames(property, collected);
+  }
+  if (schema.additionalProperties && schema.additionalProperties !== true) {
+    collectReferencedTypeNames(schema.additionalProperties, collected);
+  }
+  return [...collected];
+}
 function getPrimarySchema(content) {
   if (!content) {
     return void 0;
@@ -99,6 +278,9 @@ function parsePaths(document, docUrl, config) {
         continue;
       }
       const moduleName = config.moduleName?.(docUrl) ?? "services";
+      if (config.ignoreUrl?.(apiPath, method, docUrl)) {
+        continue;
+      }
       const functionName = sanitizeIdentifier(
         config.renameMethod?.(apiPath, method) ?? buildDefaultMethodName(apiPath, method)
       );
@@ -108,7 +290,43 @@ function parsePaths(document, docUrl, config) {
       const requestBodySchema = getPrimarySchema(operation.requestBody?.content);
       const responseSchema = getSuccessResponse(operation.responses);
       const hasRequestParams = queryParams.length > 0 || pathParams.length > 0 || Boolean(requestBodySchema);
-      const requestTypeName = hasRequestParams ? buildTypeName(functionName, "Request") : void 0;
+      const bodyType = requestBodySchema ? schemaToTs(requestBodySchema) : void 0;
+      const requestImportTypes = collectReferencedTypeNames(requestBodySchema);
+      for (const param of queryParams) {
+        requestImportTypes.push(...collectReferencedTypeNames(param.schema));
+      }
+      for (const param of pathParams) {
+        requestImportTypes.push(...collectReferencedTypeNames(param.schema));
+      }
+      const pathFields = pathParams.map((param) => `${param.name}: ${schemaToTs(param.schema)};`);
+      const queryFields = queryParams.map((param) => `${param.name}${param.required ? "" : "?"}: ${schemaToTs(param.schema)};`);
+      const requestTypeParts = [];
+      if (bodyType) {
+        requestTypeParts.push(bodyType);
+      }
+      if (pathFields.length) {
+        if (config.mergeParams) {
+          requestTypeParts.push(`{ ${pathFields.join(" ")} }`);
+        } else {
+          requestTypeParts.push(`{ path: { ${pathFields.join(" ")} } }`);
+        }
+      }
+      if (queryFields.length) {
+        if (config.flattenQueryParam && queryParams.length === 1 && queryParams[0].schema?.$ref) {
+          if (config.mergeParams) {
+            requestTypeParts.push(schemaToTs(queryParams[0].schema));
+          } else {
+            requestTypeParts.push(`{ query: ${schemaToTs(queryParams[0].schema)} }`);
+          }
+        } else {
+          if (config.mergeParams) {
+            requestTypeParts.push(`{ ${queryFields.join(" ")} }`);
+          } else {
+            requestTypeParts.push(`{ query: { ${queryFields.join(" ")} } }`);
+          }
+        }
+      }
+      const requestTypeExpression = hasRequestParams ? requestTypeParts.join(" & ") || "unknown" : void 0;
       operations.push({
         docUrl,
         moduleName,
@@ -123,7 +341,8 @@ function parsePaths(document, docUrl, config) {
         pathParams,
         requestBodySchema,
         responseSchema,
-        requestTypeName,
+        requestTypeExpression,
+        requestImportTypes,
         responseTypeName: responseSchema ? buildTypeName(functionName, "Response") : void 0,
         fileBaseName: functionName
       });
@@ -149,13 +368,14 @@ async function loadOpenApiDocument(docUrl) {
 }
 
 // src/generators/genIndex.ts
-function generateIndexFile(operations, config) {
-  const exports = operations.map((operation) => {
-    return `export * from "./${operation.moduleName}/${operation.fileBaseName}";`;
-  });
+function generateIndexFile(operations, _config) {
+  const exportSet = /* @__PURE__ */ new Set();
+  for (const operation of operations) {
+    exportSet.add(`export * from "./${operation.moduleName}/${operation.fileBaseName}";`);
+  }
   return `/* eslint-disable */
 // Auto-generated by swgto.
-${exports.join("\n")}
+${[...exportSet].join("\n")}
 `;
 }
 
@@ -171,17 +391,43 @@ function buildFunctionDoc(operation, typeImportPath, requestParamType) {
   lines.push(`@path ${operation.path}`);
   lines.push(`@requestPath ${operation.requestPath}`);
   lines.push(`@method ${operation.method.toUpperCase()}`);
-  lines.push("@template T");
   lines.push(`@param ${requestParamType === "void" ? "[params]" : `{import(${JSON.stringify(typeImportPath)}).${requestParamType}} params`}`);
   lines.push("@param [config]");
-  lines.push("@returns {Promise<T>}");
+  if (operation.responseTypeName) {
+    lines.push(`@returns {Promise<import(${JSON.stringify(typeImportPath)}).${operation.responseTypeName}>}`);
+  } else {
+    lines.push("@template T");
+    lines.push("@returns {Promise<T>}");
+  }
   return ["/**", ...lines.map((line) => ` * ${line}`), " */"].join("\n");
 }
-function generateJsRequestFile(operation, httpClientPath, typeImportPath) {
-  const requestParamType = operation.requestTypeName ?? "void";
-  const queryLine = operation.queryParams.length ? "    params: params?.query,\n" : "";
-  const bodyLine = operation.requestBodySchema ? "    data: params?.body,\n" : "";
-  const pathLine = operation.pathParams.length ? "    url: buildUrl(params?.path),\n" : `    url: ${JSON.stringify(operation.requestPath)},
+function renderFunction(operation, useGenericUrl, mergeParams) {
+  const queryLine = operation.queryParams.length ? `    params: ${mergeParams ? "params" : "params?.query"},
+` : "";
+  const bodyOnly = Boolean(operation.requestBodySchema) && !operation.queryParams.length && !operation.pathParams.length;
+  const bodyLine = operation.requestBodySchema ? `    data: ${mergeParams ? "params" : bodyOnly ? "params" : "params?.body"},
+` : "";
+  const pathArg = mergeParams ? "params" : "params?.path";
+  const urlValue = useGenericUrl && operation.pathParams.length ? `buildUrl(${JSON.stringify(operation.requestPath)}, ${pathArg})` : operation.pathParams.length ? `buildUrl(${pathArg})` : JSON.stringify(operation.requestPath);
+  const pathLine = `    url: ${urlValue},
+`;
+  return `export async function ${operation.functionName}(params, config) {
+  return request({
+${pathLine}    method: ${JSON.stringify(operation.method)},
+${queryLine}${bodyLine}    ...config,
+  });
+}`;
+}
+function generateJsRequestFile(operation, httpClientPath, typeImportPath, mergeParams = false) {
+  const requestParamType = operation.requestTypeExpression ?? "void";
+  const queryLine = operation.queryParams.length ? `    params: ${mergeParams ? "params" : "params?.query"},
+` : "";
+  const bodyOnly = Boolean(operation.requestBodySchema) && !operation.queryParams.length && !operation.pathParams.length;
+  const bodyLine = operation.requestBodySchema ? `    data: ${mergeParams ? "params" : bodyOnly ? "params" : "params?.body"},
+` : "";
+  const pathArg = mergeParams ? "params" : "params?.path";
+  const pathLine = operation.pathParams.length ? `    url: buildUrl(${pathArg}),
+` : `    url: ${JSON.stringify(operation.requestPath)},
 `;
   const buildUrlHelper = operation.pathParams.length ? `
 function buildUrl(path) {
@@ -202,6 +448,26 @@ ${queryLine}${bodyLine}    ...config,
 }
 `;
 }
+function generateJsModuleFile(operations, httpClientPath, typeImportPath, mergeParams = false) {
+  const needsBuildUrl = operations.some((op) => op.pathParams.length > 0);
+  const buildUrlHelper = needsBuildUrl ? `
+function buildUrl(url, path) {
+  return url.replace(/\\{([^}]+)\\}/g, (_, key) => String(path?.[key] ?? ''));
+}
+` : "";
+  const functions = operations.map((op) => {
+    const doc = buildFunctionDoc(op, typeImportPath, op.requestTypeExpression ?? "void");
+    return `${doc}
+
+${renderFunction(op, true, mergeParams)}`;
+  }).join("\n\n");
+  return `/* eslint-disable */
+// Auto-generated by swgto.
+import request from ${JSON.stringify(httpClientPath)};
+${buildUrlHelper}
+${functions}
+`;
+}
 
 // src/generators/genRequestTs.ts
 function buildFunctionDoc2(operation) {
@@ -217,20 +483,33 @@ function buildFunctionDoc2(operation) {
   }
   return ["/**", ...lines.map((line) => ` * ${line}`), " */", ""].join("\n");
 }
-function generateTsRequestFile(operation, httpClientPath, typeImportPath) {
+function renderFunction2(operation, useGenericUrl, mergeParams) {
+  const requestArg = operation.requestTypeExpression ? `params: ${operation.requestTypeExpression}, config?: RequestConfig` : "params?: void, config?: RequestConfig";
+  const defaultResponseType = operation.responseTypeName ?? "unknown";
+  const bodyOnly = Boolean(operation.requestBodySchema) && !operation.queryParams.length && !operation.pathParams.length;
+  const bodyLine = operation.requestBodySchema ? `    data: ${mergeParams ? "params" : bodyOnly ? "params" : "params?.body"},
+` : "";
+  const queryLine = operation.queryParams.length ? `    params: ${mergeParams ? "params" : "params?.query"},
+` : "";
+  const pathArg = mergeParams ? "params" : "params?.path";
+  const urlValue = useGenericUrl && operation.pathParams.length ? `buildUrl(${JSON.stringify(operation.requestPath)}, ${pathArg})` : operation.pathParams.length ? `buildUrl(${pathArg})` : JSON.stringify(operation.requestPath);
+  const pathLine = `    url: ${urlValue},
+`;
+  return `${buildFunctionDoc2(operation)}export async function ${operation.functionName}<T = ${defaultResponseType}>(${requestArg}): Promise<T> {
+  return request<T>({
+${pathLine}    method: ${JSON.stringify(operation.method)},
+${queryLine}${bodyLine}    ...config,
+  });
+}`;
+}
+function generateTsRequestFile(operation, httpClientPath, typeImportPath, mergeParams = false) {
   const importTypes = [
-    operation.requestTypeName,
+    ...operation.requestImportTypes,
     operation.responseTypeName,
     "RequestConfig"
   ].filter((value, index, array) => Boolean(value) && array.indexOf(value) === index);
   const importLine = importTypes.length ? `import type { ${importTypes.join(", ")} } from ${JSON.stringify(typeImportPath)};
 ` : "";
-  const requestArg = operation.requestTypeName ? `params: ${operation.requestTypeName}, config?: RequestConfig` : "params?: void, config?: RequestConfig";
-  const defaultResponseType = operation.responseTypeName ?? "unknown";
-  const bodyLine = operation.requestBodySchema ? "    data: params?.body,\n" : "";
-  const queryLine = operation.queryParams.length ? "    params: params?.query,\n" : "";
-  const pathLine = operation.pathParams.length ? "    url: buildUrl(params?.path),\n" : `    url: ${JSON.stringify(operation.requestPath)},
-`;
   const buildUrlHelper = operation.pathParams.length ? `
 function buildUrl(path?: Record<string, unknown>): string {
   return ${JSON.stringify(operation.requestPath)}.replace(/\\{([^}]+)\\}/g, (_, key) => String(path?.[key] ?? ''));
@@ -241,74 +520,31 @@ function buildUrl(path?: Record<string, unknown>): string {
 import request from ${JSON.stringify(httpClientPath)};
 ${importLine}
 ${buildUrlHelper}
-${buildFunctionDoc2(operation)}
-export async function ${operation.functionName}<T = ${defaultResponseType}>(${requestArg}): Promise<T> {
-  return request<T>({
-${pathLine}    method: ${JSON.stringify(operation.method)},
-${queryLine}${bodyLine}    ...config,
-  });
-}
+${renderFunction2(operation, false, mergeParams)}
 `;
 }
-
-// src/generators/schemaToTs.ts
-function formatPropertyName(name) {
-  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name);
-}
-function refToTypeName(ref) {
-  const parts = ref.split("/");
-  return parts[parts.length - 1] || "unknown";
-}
-function schemaToTs(schema) {
-  if (!schema) {
-    return "unknown";
-  }
-  if (schema.$ref) {
-    return refToTypeName(schema.$ref);
-  }
-  if (schema.enum?.length) {
-    return schema.enum.map((item) => JSON.stringify(item)).join(" | ");
-  }
-  if (schema.anyOf?.length) {
-    return schema.anyOf.map((item) => schemaToTs(item)).join(" | ");
-  }
-  if (schema.oneOf?.length) {
-    return schema.oneOf.map((item) => schemaToTs(item)).join(" | ");
-  }
-  if (schema.allOf?.length) {
-    return schema.allOf.map((item) => schemaToTs(item)).join(" & ");
-  }
-  if (schema.type === "array") {
-    return `${schemaToTs(schema.items)}[]`;
-  }
-  if (schema.type === "object" || schema.properties) {
-    const requiredSet = new Set(schema.required ?? []);
-    const properties = Object.entries(schema.properties ?? {}).map(([key, value]) => {
-      const optional = requiredSet.has(key) ? "" : "?";
-      return `${formatPropertyName(key)}${optional}: ${schemaToTs(value)};`;
-    });
-    if (!properties.length && schema.additionalProperties) {
-      const valueType = schema.additionalProperties === true ? "unknown" : schemaToTs(schema.additionalProperties);
-      return `{ [key: string]: ${valueType} }`;
-    }
-    return `{ ${properties.join(" ")} }`;
-  }
-  switch (schema.type) {
-    case "integer":
-    case "number":
-      return "number";
-    case "boolean":
-      return "boolean";
-    case "string":
-      return "string";
-    case "null":
-      return "null";
-    default:
-      return "unknown";
+function generateTsModuleFile(operations, httpClientPath, typeImportPath, mergeParams = false) {
+  const importTypeSet = /* @__PURE__ */ new Set();
+  for (const op of operations) {
+    for (const t of op.requestImportTypes) importTypeSet.add(t);
+    if (op.responseTypeName) importTypeSet.add(op.responseTypeName);
   }
+  importTypeSet.add("RequestConfig");
+  const importLine = `import type { ${[...importTypeSet].join(", ")} } from ${JSON.stringify(typeImportPath)};
+`;
+  const needsBuildUrl = operations.some((op) => op.pathParams.length > 0);
+  const buildUrlHelper = needsBuildUrl ? `
+function buildUrl(url: string, path?: Record<string, unknown>): string {
+  return url.replace(/\\{([^}]+)\\}/g, (_, key) => String(path?.[key] ?? ''));
 }
-function toTypePropertyName(name) {
-  return formatPropertyName(name);
+` : "";
+  const functions = operations.map((op) => renderFunction2(op, true, mergeParams)).join("\n\n");
+  return `/* eslint-disable */
+// Auto-generated by swgto.
+import request from ${JSON.stringify(httpClientPath)};
+${importLine}${buildUrlHelper}
+${functions}
+`;
 }
 
 // src/generators/genTypes.ts
@@ -328,21 +564,17 @@ function buildSchemaDoc(schema) {
   }
   return formatDocLines(lines);
 }
-function buildParameterDoc(parameter, fallback) {
-  const lines = [parameter.description ?? fallback];
-  if (parameter.required) {
-    lines.push("@required");
-  }
-  if (parameter.example !== void 0) {
-    lines.push(`@example ${JSON.stringify(parameter.example)}`);
-  }
-  return formatDocLines(lines);
+function jsdocToInline(doc, indent) {
+  return doc.split("\n").filter((line) => {
+    const t = line.trim();
+    return t !== "/**" && t !== "*/" && !t.startsWith("/**");
+  }).map((line) => `${indent}// ${line.replace(/^\s*\* ?/, "")}`);
 }
 function renderObjectFields(fields, indent = "") {
   const lines = [];
   for (const field of fields) {
     if (field.doc) {
-      lines.push(...field.doc.split("\n").map((line) => `${indent}${line}`));
+      lines.push(...jsdocToInline(field.doc, indent));
     }
     lines.push(`${indent}${field.name}${field.optional ? "?" : ""}: ${field.type};`);
   }
@@ -370,56 +602,6 @@ ${body}
 }
 function renderOperationTypes(operation) {
   const blocks = [];
-  if (operation.requestTypeName) {
-    const fields = [];
-    const pathFields = [];
-    const queryFields = [];
-    for (const param of operation.pathParams) {
-      pathFields.push({
-        name: toTypePropertyName(param.name),
-        type: schemaToTs(param.schema),
-        optional: false,
-        doc: buildParameterDoc(param, `Path parameter: ${param.name}`)
-      });
-    }
-    for (const param of operation.queryParams) {
-      queryFields.push({
-        name: toTypePropertyName(param.name),
-        type: schemaToTs(param.schema),
-        optional: !param.required,
-        doc: buildParameterDoc(param, `Query parameter: ${param.name}`)
-      });
-    }
-    if (operation.requestBodySchema) {
-      const doc = buildSchemaDoc(operation.requestBodySchema);
-      if (doc) {
-        fields.push(...doc.split("\n"));
-      }
-      fields.push(`body${operation.requestBodySchema.nullable ? "?" : ""}: ${schemaToTs(operation.requestBodySchema)};`);
-    }
-    if (pathFields.length) {
-      fields.push("/** Path parameters */");
-      fields.push("path: {");
-      fields.push(...renderObjectFields(pathFields, "  "));
-      fields.push("};");
-    }
-    if (queryFields.length) {
-      fields.push("/** Query parameters */");
-      fields.push("query: {");
-      fields.push(...renderObjectFields(queryFields, "  "));
-      fields.push("};");
-    }
-    const requestDoc = formatDocLines(
-      [
-        operation.summary,
-        operation.description
-      ].filter((value) => Boolean(value))
-    );
-    blocks.push(`${requestDoc ? `${requestDoc}
-` : ""}export interface ${operation.requestTypeName} {
-${fields.map((line) => `  ${line}`).join("\n")}
-}`);
-  }
   if (operation.responseTypeName) {
     const responseDoc = buildSchemaDoc(operation.responseSchema);
     blocks.push(`${responseDoc ? `${responseDoc}
@@ -433,7 +615,7 @@ function renderComponentSchemas(document) {
   });
 }
 function toJSDocType(typeText) {
-  return typeText.replace(/;/g, "").replace(/\?/g, "=");
+  return typeText.replace(/;\s*/g, ", ").replace(/,\s*\}/g, " }");
 }
 function generateTypesFile(documentMap, operations, config) {
   if (config.outputType === "js") {
@@ -450,13 +632,6 @@ function generateTypesFile(documentMap, operations, config) {
       }
     }
     for (const operation of operations) {
-      if (operation.requestTypeName) {
-        const rendered = renderOperationTypes(operation).find((line) => line.startsWith(`export interface ${operation.requestTypeName}`));
-        if (rendered) {
-          const body = rendered.replace(`export interface ${operation.requestTypeName} `, "").trim();
-          parts2.push(`/** @typedef ${body} ${operation.requestTypeName} */`);
-        }
-      }
       if (operation.responseTypeName) {
         parts2.push(`/** @typedef {${toJSDocType(schemaToTs(operation.responseSchema))}} ${operation.responseTypeName} */`);
       }
@@ -481,16 +656,6 @@ function generateTypesFile(documentMap, operations, config) {
   return `${parts.filter(Boolean).join("\n\n")}
 `;
 }
-function generateApiDtsContent(operations, config) {
-  const lines = ["// Auto-generated by swgto.", 'export * from "./index";', `export * from "./${config.typeName}";`];
-  for (const operation of operations) {
-    const paramsType = operation.requestTypeName ?? "void";
-    const responseType = operation.responseTypeName ?? "unknown";
-    lines.push(`export declare function ${operation.functionName}<T = ${responseType}>(params${paramsType === "void" ? "?" : ""}: ${paramsType}, config?: import("./index").RequestConfig): Promise<T>;`);
-  }
-  return `${lines.join("\n")}
-`;
-}
 
 // src/utils/fs.ts
 import { mkdir, rm, writeFile } from "fs/promises";
@@ -503,12 +668,17 @@ async function writeTextFile(filePath, content) {
   await writeFile(filePath, content, "utf8");
 }
 async function removeDir(dirPath) {
-  await rm(dirPath, { recursive: true, force: true });
+  try {
+    await rm(dirPath, { recursive: true, force: true });
+  } catch {
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    await rm(dirPath, { recursive: true, force: true });
+  }
 }
 
 // src/generate.ts
-function getRootImportPath(fileKind, typeName) {
-  return fileKind === "types" ? `../${typeName}` : "../api";
+function getRootImportPath(typeName) {
+  return `../${typeName}`;
 }
 async function generateFromConfig(cwd = process.cwd()) {
   const { configPath, config } = await loadConfig(cwd);
@@ -516,6 +686,7 @@ async function generateFromConfig(cwd = process.cwd()) {
   const operations = [];
   if (config.cleanOutput) {
     await removeDir(path3.join(cwd, config.outputDir));
+    console.log(`Cleaned output directory: ${config.outputDir}`);
   }
   for (const docUrl of config.docUrls) {
     const document = await loadOpenApiDocument(docUrl);
@@ -525,33 +696,45 @@ async function generateFromConfig(cwd = process.cwd()) {
   const grouped = groupByPrefix(operations);
   const files = [];
   for (const [moduleName, moduleOperations] of Object.entries(grouped)) {
-    for (const operation of moduleOperations) {
-      const relativeFile = path3.join(config.outputDir, moduleName, `${operation.fileBaseName}.${config.outputType}`);
-      const absoluteFile = path3.join(cwd, relativeFile);
-      const content = config.outputType === "ts" ? generateTsRequestFile(operation, config.httpClientPath, getRootImportPath("types", config.typeName)) : generateJsRequestFile(operation, config.httpClientPath, getRootImportPath("api", config.typeName));
-      await writeTextFile(absoluteFile, content);
-      files.push(relativeFile);
+    if (config.fileNaming === "module") {
+      const controllerMap = groupByController(moduleOperations);
+      for (const [controllerName, controllerOperations] of Object.entries(controllerMap)) {
+        const relativeFile = path3.join(config.outputDir, moduleName, `${controllerName}.${config.outputType}`);
+        const absoluteFile = path3.join(cwd, relativeFile);
+        const content = config.outputType === "ts" ? generateTsModuleFile(controllerOperations, config.httpClientPath, getRootImportPath(config.typeName), config.mergeParams) : generateJsModuleFile(controllerOperations, config.httpClientPath, getRootImportPath(config.typeName), config.mergeParams);
+        for (const op of controllerOperations) {
+          op.fileBaseName = controllerName;
+        }
+        await writeTextFile(absoluteFile, content);
+        files.push(relativeFile);
+      }
+    } else {
+      for (const operation of moduleOperations) {
+        const relativeFile = path3.join(config.outputDir, moduleName, `${operation.fileBaseName}.${config.outputType}`);
+        const absoluteFile = path3.join(cwd, relativeFile);
+        const content = config.outputType === "ts" ? generateTsRequestFile(operation, config.httpClientPath, getRootImportPath(config.typeName), config.mergeParams) : generateJsRequestFile(operation, config.httpClientPath, getRootImportPath(config.typeName), config.mergeParams);
+        await writeTextFile(absoluteFile, content);
+        files.push(relativeFile);
+      }
     }
   }
   const typesContent = generateTypesFile(documentMap, operations, config);
-  const apiDtsContent = generateApiDtsContent(operations, config);
   const indexContent = generateIndexFile(operations, config);
   const typesFile = path3.join(cwd, config.outputDir, `${config.typeName}.${config.outputType === "ts" ? "ts" : "js"}`);
-  const apiDtsFile = path3.join(cwd, config.outputDir, "api.d.ts");
   const indexFile = path3.join(cwd, config.outputDir, `index.${config.outputType}`);
   await writeTextFile(typesFile, typesContent);
-  await writeTextFile(apiDtsFile, apiDtsContent);
   await writeTextFile(indexFile, indexContent);
   files.push(
     path3.relative(cwd, typesFile),
-    path3.relative(cwd, apiDtsFile),
     path3.relative(cwd, indexFile)
   );
   return {
     configPath,
     files,
     operationCount: operations.length,
-    moduleCount: Object.keys(grouped).length
+    moduleCount: Object.keys(grouped).length,
+    apiFileCount: files.length - 2
+    // exclude types + index
   };
 }
 

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   generateFromConfig
-} from "./chunk-RRFCLHNU.js";
+} from "./chunk-4OK6R2K5.js";
 
 // src/cli.ts
 async function main() {
@@ -10,8 +10,8 @@ async function main() {
     const result = await generateFromConfig(process.cwd());
     const elapsedMs = Date.now() - startedAt;
     console.log(`swgto loaded config: ${result.configPath}`);
-    console.log(`Generated ${result.operationCount} API files in ${result.moduleCount} module(s).`);
-    console.log(`Wrote ${result.files.length} files, including index and api.d.ts.`);
+    console.log(`Generated ${result.apiFileCount} api file(s), ${result.operationCount} operation(s) in ${result.moduleCount} module(s).`);
+    console.log(`Wrote ${result.files.length} file(s) total (including types, index).`);
     console.log(`Done in ${elapsedMs}ms.`);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);

package/dist/index.d.ts

@@ -3,6 +3,7 @@ interface GenerateResult {
     files: string[];
     operationCount: number;
     moduleCount: number;
+    apiFileCount: number;
 }
 declare function generateFromConfig(cwd?: string): Promise<GenerateResult>;
 
@@ -13,11 +14,15 @@ interface SwaggerTsConfig {
     httpClientPath: string;
     renameMethod?: (path: string, method: string) => string;
     resolveRequestPath?: (path: string, method: string, docUrl: string) => string;
+    ignoreUrl?: (path: string, method: string, docUrl: string) => boolean;
     outputDir?: string;
     moduleName?: (docUrl: string) => string;
     outputType?: OutputType;
     typeName?: string;
     cleanOutput?: boolean;
+    fileNaming?: 'module' | 'path';
+    flattenQueryParam?: boolean;
+    mergeParams?: boolean;
 }
 
 export { type GenerateResult, type RequestConfig, type SwaggerTsConfig, generateFromConfig };

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   generateFromConfig
-} from "./chunk-RRFCLHNU.js";
+} from "./chunk-4OK6R2K5.js";
 export {
   generateFromConfig
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swgto-ts",
-  "version": "0.1.0",
+  "version": "2.0.0",
   "description": "Generate API request files from OpenAPI 3.x documents.",
   "license": "MIT",
   "type": "module",
@@ -16,7 +16,7 @@
   "scripts": {
     "build": "tsup src/index.ts src/cli.ts --format esm --dts --clean",
     "dev": "tsup src/index.ts src/cli.ts --format esm --dts --watch",
-    "test": "vitest run"
+    "test": "tsx ./src/cli.ts"
   },
   "keywords": [
     "openapi",
@@ -29,7 +29,9 @@
     "node": ">=18"
   },
   "dependencies": {
-    "jiti": "^2.4.2"
+    "jiti": "^2.4.2",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.21.0"
   },
   "devDependencies": {
     "@types/node": "^24.6.0",