swgto-ts 3.0.1 → 3.1.0

package/README.md

@@ -81,6 +81,7 @@ export interface SwaggerTsConfig {
   fileNaming?: 'module' | 'path'
   flattenQueryParam?: boolean
   mergeParams?: boolean
+  flattenOnGet?: boolean
   apiDocs?: ApiDocsConfig
 }
 ```
@@ -102,6 +103,7 @@ export interface SwaggerTsConfig {
 | `cleanOutput`        | `boolean`                           | `false`      | 生成前是否清空输出目录                                                                                                                 |
 | `flattenQueryParam`  | `boolean`                           | `false`      | 当 query 参数只有一个且为 `$ref` 引用类型时，直接用引用类型代替 `{ query: RefType }`                                                   |
 | `mergeParams`        | `boolean`                           | `false`      | 合并参数层级：`true` 时展平 `path/query/body` 嵌套，直接使用 `params: { field1, field2 }` 代替 `params: { path: {...}, query: {...} }` |
+| `flattenOnGet`       | `boolean`                           | `false`      | GET 请求专用展平：将所有 body/query/path 中的 `$ref` 参数展开为顶层交叉类型，彻底消除嵌套。详见 [GET 参数展平](#get-参数展平)            |
 | `apiDocs`            | `ApiDocsConfig`                     | 见说明       | 自动生成 API 文档（HTML/Markdown），详细配置见 [API 文档生成](#api-文档生成)                                                         |
 
 ### 函数名生成规则
@@ -148,6 +150,26 @@ getUser({ path: { id: '1' }, query: { name: 'foo' } })
 getUser({ id: '1', name: 'foo' })
 ```
 
+### GET 参数展平
+
+`flattenOnGet: true` 专门解决 GET 请求中 body 和 query 参数嵌套的问题。当 GET 请求同时包含 body 参数（如 `userDTO`）和 query 参数（如 `pageQuery`）时，会将所有 `$ref` 类型的参数展开为顶层交叉类型，实现 `{...userDTO, ...pageQuery}` 的效果。
+
+**背景**：部分后端定义 GET 请求时，参数在 body 和 query 中分散定义，但实际入参是合并平铺的。仅靠 `mergeParams` 会保留 body 内部的属性名作为嵌套字段。
+
+**示例**：一个 GET 请求的 body 中有 `adminUserVO: AdminUserVO`，query 中有 `pageRequest: SessionPageRequestDTO`
+
+```ts
+// flattenOnGet: false（默认），body 属性名保留为嵌套字段
+get_ai_sessions({ adminUserVO: {...}, pageRequest: {...} })
+// 类型：{ adminUserVO: AdminUserVO; pageRequest: SessionPageRequestDTO; }
+
+// flattenOnGet: true，$ref 参数全部展开到顶层
+get_ai_sessions({ ...adminUserVOFields, ...pageRequestFields })
+// 类型：AdminUserVO & SessionPageRequestDTO
+```
+
+> **注意**：`flattenOnGet` 仅对 GET 请求生效，且通常与 `mergeParams` 和 `flattenQueryParam` 一起使用效果最佳。该选项会同时影响生成的类型签名和函数体实现。
+
 ### API 文档生成
 
 配置 `apiDocs` 可在生成代码的同时，自动输出一份人类可读的 API 文档：

package/dist/{chunk-OMXGXES2.js → chunk-PAFR76SO.js}

@@ -52,6 +52,7 @@ async function loadConfig(cwd) {
     fileNaming: rawConfig.fileNaming ?? "path",
     flattenQueryParam: rawConfig.flattenQueryParam ?? false,
     mergeParams: rawConfig.mergeParams ?? false,
+    flattenOnGet: rawConfig.flattenOnGet ?? false,
     apiDocs: {
       enable: rawConfig.apiDocs?.enable ?? false,
       output: rawConfig.apiDocs?.output ?? defaultOutput,
@@ -259,28 +260,60 @@ function parsePaths(document, docUrl, config) {
       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(" ")} } }`);
+      const isFlattenOnGet = config.flattenOnGet && method === "get";
+      if (isFlattenOnGet) {
+        const flatFields = [];
+        if (requestBodySchema) {
+          if (!requestBodySchema.$ref && requestBodySchema.properties) {
+            for (const [name, schema] of Object.entries(requestBodySchema.properties)) {
+              if (schema.$ref) {
+                requestTypeParts.push(schemaToTs(schema));
+              } else {
+                const required = requestBodySchema.required?.includes(name) ?? false;
+                flatFields.push(`${name}${required ? "" : "?"}: ${schemaToTs(schema)}`);
+              }
+            }
+          } else {
+            requestTypeParts.push(bodyType);
+          }
         }
-      }
-      if (queryFields.length) {
-        if (config.flattenQueryParam && queryParams.length === 1 && queryParams[0].schema?.$ref) {
-          if (config.mergeParams) {
-            requestTypeParts.push(schemaToTs(queryParams[0].schema));
+        for (const param of queryParams) {
+          if (param.schema?.$ref) {
+            requestTypeParts.push(schemaToTs(param.schema));
           } else {
-            requestTypeParts.push(`{ query: ${schemaToTs(queryParams[0].schema)} }`);
+            flatFields.push(`${param.name}${param.required ? "" : "?"}: ${schemaToTs(param.schema)}`);
           }
-        } else {
+        }
+        for (const field of pathFields) {
+          flatFields.push(field);
+        }
+        if (flatFields.length) {
+          requestTypeParts.push(`{ ${flatFields.join(" ")} }`);
+        }
+      } else {
+        if (bodyType) {
+          requestTypeParts.push(bodyType);
+        }
+        if (pathFields.length) {
           if (config.mergeParams) {
-            requestTypeParts.push(`{ ${queryFields.join(" ")} }`);
+            requestTypeParts.push(`{ ${pathFields.join(" ")} }`);
           } else {
-            requestTypeParts.push(`{ query: { ${queryFields.join(" ")} } }`);
+            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(" ")} } }`);
+            }
           }
         }
       }
@@ -338,6 +371,16 @@ ${[...exportSet].join("\n")}
 }
 
 // src/generators/genRequestJs.ts
+function isSimpleTypeRef(name) {
+  return /^[\w.]+$/.test(name);
+}
+function buildParamTag(requestParamType, typeImportPath) {
+  if (requestParamType === "void") return "[params]";
+  if (isSimpleTypeRef(requestParamType)) {
+    return `{import(${JSON.stringify(typeImportPath)}).${requestParamType}} params`;
+  }
+  return `{${requestParamType}} params`;
+}
 function buildFunctionDoc(operation, typeImportPath, requestParamType) {
   const lines = [];
   if (operation.summary) {
@@ -349,7 +392,7 @@ function buildFunctionDoc(operation, typeImportPath, requestParamType) {
   lines.push(`@path ${operation.path}`);
   lines.push(`@requestPath ${operation.requestPath}`);
   lines.push(`@method ${operation.method.toUpperCase()}`);
-  lines.push(`@param ${requestParamType === "void" ? "[params]" : `{import(${JSON.stringify(typeImportPath)}).${requestParamType}} params`}`);
+  lines.push(`@param ${buildParamTag(requestParamType, typeImportPath)}`);
   lines.push("@param [config]");
   if (operation.responseTypeName) {
     lines.push(`@returns {Promise<import(${JSON.stringify(typeImportPath)}).${operation.responseTypeName}>}`);
@@ -359,31 +402,43 @@ function buildFunctionDoc(operation, typeImportPath, requestParamType) {
   }
   return ["/**", ...lines.map((line) => ` * ${line}`), " */"].join("\n");
 }
-function renderFunction(operation, useGenericUrl, mergeParams) {
-  const queryLine = operation.queryParams.length ? `    params: ${mergeParams ? "params" : "params?.query"},
+function renderFunction(operation, useGenericUrl, mergeParams, flattenOnGet = false) {
+  const effectiveMerge = mergeParams || flattenOnGet && operation.method === "get";
+  const queryLine = operation.queryParams.length ? `    params: ${effectiveMerge ? "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 hasBodySchema = Boolean(operation.requestBodySchema);
+  const needsCleanData = effectiveMerge && hasBodySchema && operation.pathParams.length > 0;
+  const destructureLine = needsCleanData ? `  const { ${operation.pathParams.map((p) => p.name).join(", ")}, ...requestData } = params;
+` : "";
+  const dataValue = needsCleanData ? "requestData" : effectiveMerge ? "params" : bodyOnly ? "params" : "params?.body";
+  const bodyLine = hasBodySchema ? `    data: ${dataValue},
 ` : "";
-  const pathArg = mergeParams ? "params" : "params?.path";
+  const pathArg = effectiveMerge ? "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({
+${destructureLine}  return request({
 ${pathLine}    method: ${JSON.stringify(operation.method)},
 ${queryLine}${bodyLine}    ...config,
   });
 }`;
 }
-function generateJsRequestFile(operation, httpClientPath, typeImportPath, mergeParams = false) {
+function generateJsRequestFile(operation, httpClientPath, typeImportPath, mergeParams = false, flattenOnGet = false) {
+  const effectiveMerge = mergeParams || flattenOnGet && operation.method === "get";
   const requestParamType = operation.requestTypeExpression ?? "void";
-  const queryLine = operation.queryParams.length ? `    params: ${mergeParams ? "params" : "params?.query"},
+  const queryLine = operation.queryParams.length ? `    params: ${effectiveMerge ? "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 hasBodySchema = Boolean(operation.requestBodySchema);
+  const needsCleanData = effectiveMerge && hasBodySchema && operation.pathParams.length > 0;
+  const destructureLine = needsCleanData ? `  const { ${operation.pathParams.map((p) => p.name).join(", ")}, ...requestData } = params;
 ` : "";
-  const pathArg = mergeParams ? "params" : "params?.path";
+  const dataValue = needsCleanData ? "requestData" : effectiveMerge ? "params" : bodyOnly ? "params" : "params?.body";
+  const bodyLine = hasBodySchema ? `    data: ${dataValue},
+` : "";
+  const pathArg = effectiveMerge ? "params" : "params?.path";
   const pathLine = operation.pathParams.length ? `    url: buildUrl(${pathArg}),
 ` : `    url: ${JSON.stringify(operation.requestPath)},
 `;
@@ -399,14 +454,14 @@ ${buildUrlHelper}
 
 ${buildFunctionDoc(operation, typeImportPath, requestParamType)}
 export async function ${operation.functionName}(params, config) {
-  return request({
+${destructureLine}  return request({
 ${pathLine}    method: ${JSON.stringify(operation.method)},
 ${queryLine}${bodyLine}    ...config,
   });
 }
 `;
 }
-function generateJsModuleFile(operations, httpClientPath, typeImportPath, mergeParams = false) {
+function generateJsModuleFile(operations, httpClientPath, typeImportPath, mergeParams = false, flattenOnGet = false) {
   const needsBuildUrl = operations.some((op) => op.pathParams.length > 0);
   const buildUrlHelper = needsBuildUrl ? `
 function buildUrl(url, path) {
@@ -417,7 +472,7 @@ function buildUrl(url, path) {
     const doc = buildFunctionDoc(op, typeImportPath, op.requestTypeExpression ?? "void");
     return `${doc}
 
-${renderFunction(op, true, mergeParams)}`;
+${renderFunction(op, true, mergeParams, flattenOnGet)}`;
   }).join("\n\n");
   return `/* eslint-disable */
 // Auto-generated by swgto.
@@ -441,26 +496,32 @@ function buildFunctionDoc2(operation) {
   }
   return ["/**", ...lines.map((line) => ` * ${line}`), " */", ""].join("\n");
 }
-function renderFunction2(operation, useGenericUrl, mergeParams) {
+function renderFunction2(operation, useGenericUrl, mergeParams, flattenOnGet = false) {
+  const effectiveMerge = mergeParams || flattenOnGet && operation.method === "get";
   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 hasBodySchema = Boolean(operation.requestBodySchema);
+  const needsCleanData = effectiveMerge && hasBodySchema && operation.pathParams.length > 0;
+  const destructureLine = needsCleanData ? `  const { ${operation.pathParams.map((p) => p.name).join(", ")}, ...requestData } = params;
+` : "";
+  const dataValue = needsCleanData ? "requestData" : effectiveMerge ? "params" : bodyOnly ? "params" : "params?.body";
+  const bodyLine = hasBodySchema ? `    data: ${dataValue},
 ` : "";
-  const queryLine = operation.queryParams.length ? `    params: ${mergeParams ? "params" : "params?.query"},
+  const queryLine = operation.queryParams.length ? `    params: ${effectiveMerge ? "params" : "params?.query"},
 ` : "";
-  const pathArg = mergeParams ? "params" : "params?.path";
+  const pathArg = effectiveMerge ? "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>({
+${destructureLine}  return request<T>({
 ${pathLine}    method: ${JSON.stringify(operation.method)},
 ${queryLine}${bodyLine}    ...config,
   });
 }`;
 }
-function generateTsRequestFile(operation, httpClientPath, typeImportPath, mergeParams = false) {
+function generateTsRequestFile(operation, httpClientPath, typeImportPath, mergeParams = false, flattenOnGet = false) {
   const importTypes = [...operation.requestImportTypes, operation.responseTypeName, "RequestConfig"].filter(
     (value, index, array) => Boolean(value) && array.indexOf(value) === index
   );
@@ -476,10 +537,10 @@ function buildUrl(path?: Record<string, any>): string {
 import request from ${JSON.stringify(httpClientPath)};
 ${importLine}
 ${buildUrlHelper}
-${renderFunction2(operation, false, mergeParams)}
+${renderFunction2(operation, false, mergeParams, flattenOnGet)}
 `;
 }
-function generateTsModuleFile(operations, httpClientPath, typeImportPath, mergeParams = false) {
+function generateTsModuleFile(operations, httpClientPath, typeImportPath, mergeParams = false, flattenOnGet = false) {
   const importTypeSet = /* @__PURE__ */ new Set();
   for (const op of operations) {
     for (const t of op.requestImportTypes) importTypeSet.add(t);
@@ -494,7 +555,7 @@ function buildUrl(url: string, path?: Record<string, unknown>): string {
   return url.replace(/\\{([^}]+)\\}/g, (_, key) => String(path?.[key] ?? ''));
 }
 ` : "";
-  const functions = operations.map((op) => renderFunction2(op, true, mergeParams)).join("\n\n");
+  const functions = operations.map((op) => renderFunction2(op, true, mergeParams, flattenOnGet)).join("\n\n");
   return `/* eslint-disable */
 // Auto-generated by swgto.
 import request from ${JSON.stringify(httpClientPath)};
@@ -718,7 +779,7 @@ async function generateFromConfig(cwd = process.cwd()) {
       for (const [controllerName, controllerOperations] of Object.entries(controllerMap)) {
         const relativeFile = path4.join(config.outputDir, moduleName, `${controllerName}.${config.outputType}`);
         const absoluteFile = path4.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);
+        const content = config.outputType === "ts" ? generateTsModuleFile(controllerOperations, config.httpClientPath, getRootImportPath(config.typeName), config.mergeParams, config.flattenOnGet) : generateJsModuleFile(controllerOperations, config.httpClientPath, getRootImportPath(config.typeName), config.mergeParams, config.flattenOnGet);
         for (const op of controllerOperations) {
           op.fileBaseName = controllerName;
         }
@@ -729,7 +790,7 @@ async function generateFromConfig(cwd = process.cwd()) {
       for (const operation of moduleOperations) {
         const relativeFile = path4.join(config.outputDir, moduleName, `${operation.fileBaseName}.${config.outputType}`);
         const absoluteFile = path4.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);
+        const content = config.outputType === "ts" ? generateTsRequestFile(operation, config.httpClientPath, getRootImportPath(config.typeName), config.mergeParams, config.flattenOnGet) : generateJsRequestFile(operation, config.httpClientPath, getRootImportPath(config.typeName), config.mergeParams, config.flattenOnGet);
         await writeTextFile(absoluteFile, content);
         files.push(relativeFile);
       }

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   generateFromConfig
-} from "./chunk-OMXGXES2.js";
+} from "./chunk-PAFR76SO.js";
 import "./chunk-HBBM5HFP.js";
 
 // src/cli.ts

package/dist/index.d.ts

@@ -24,6 +24,7 @@ interface SwaggerTsConfig {
     fileNaming?: 'module' | 'path';
     flattenQueryParam?: boolean;
     mergeParams?: boolean;
+    flattenOnGet?: boolean;
     apiDocs?: ApiDocsConfig;
 }
 

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   generateFromConfig
-} from "./chunk-OMXGXES2.js";
+} from "./chunk-PAFR76SO.js";
 import "./chunk-HBBM5HFP.js";
 export {
   generateFromConfig

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swgto-ts",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "Generate API request files from OpenAPI 3.x documents.",
   "license": "MIT",
   "type": "module",
@@ -25,9 +25,6 @@
     "generator",
     "cli"
   ],
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org/"
-  },
   "engines": {
     "node": ">=18"
   },