swgto-ts 3.0.2 → 3.2.0

package/README.md

@@ -1,196 +1,218 @@
-# 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
-  apiDocs?: ApiDocsConfig
-}
-```
-
-### 字段说明
-
-| 字段                 | 类型                                | 默认值       | 说明                                                                                                                                   |
-| -------------------- | ----------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
-| `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: {...} }` |
-| `apiDocs`            | `ApiDocsConfig`                     | 见说明       | 自动生成 API 文档（HTML/Markdown），详细配置见 [API 文档生成](#api-文档生成)                                                         |
-
-### 函数名生成规则
-
-默认函数名格式为 `{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' })
-```
-
-### API 文档生成
-
-配置 `apiDocs` 可在生成代码的同时，自动输出一份人类可读的 API 文档：
-
-```ts
-export default {
-  // ... 其他配置
-  apiDocs: {
-    enable: true,
-    format: 'html',           // 'html' 或 'markdown'
-    output: 'api-docs.html',  // 输出文件名
-    title: '我的 API 文档',    // 文档标题，默认取 OpenAPI info.title
-    companyName: 'XX 公司',   // 封面公司名称（仅 HTML）
-    template: './my-template.html', // 自定义 HTML 模板路径（仅 HTML）
-    theme: './my-theme.css',  // 自定义样式文件路径（仅 HTML）
-  },
-}
-```
-
-| 配置项        | 类型                        | 默认值                  | 说明                                                           |
-| ------------- | --------------------------- | ----------------------- | -------------------------------------------------------------- |
-| `enable`      | `boolean`                   | `false`                 | 是否开启文档生成                                               |
-| `format`      | `'html' \| 'markdown'`      | `'html'`                | 输出格式：HTML 适合浏览器打印为 PDF，Markdown 适合仓库内查看   |
-| `output`      | `string`                    | `'api-docs.html'`       | 输出文件名，相对 `outputDir`                                   |
-| `title`       | `string`                    | OpenAPI `info.title`    | 文档标题                                                       |
-| `companyName` | `string`                    | 无                      | 封面上的公司名称（仅 HTML）                                    |
-| `template`    | `string`                    | 内置模板                | 自定义 HTML 模板路径（仅 HTML）。优先级：`template` 配置 > 项目根目录 `.swagger.docs.html` > 内置默认模板 |
-| `theme`       | `string`                    | 无                      | 自定义 CSS 文件路径，覆盖文档样式（仅 HTML）                   |
-
-#### HTML 文档
-
-输出为带书本风格的 HTML 页面，包含：
-- **封面页**：A4 整页，显示公司名称（如配置）、API 名称和版本号
-- **目录**：方法 + 路径 | 点线 | 摘要，点击跳转到对应接口
-- **接口卡片**：包含路径参数、查询参数、请求体、响应体的字段表格（名称 / 类型 / 必填 / 描述）
-
-可通过项目根目录的 `.swagger.docs.html` 文件自定义文档样式。如果设置了 `apiDocs.template`，则优先使用该路径的模板文件。
-
-#### Markdown 文档
-
-输出为 `.md` 文件，包含：
-- 封面区域：公司名称（如配置）、API 名称和版本号
-- 目录（Table of Contents）：所有接口的锚点链接列表
-- 每个接口的详细说明：HTTP 方法 + 路径、描述、参数表格和响应表格
-
-适合直接在代码仓库中查看或用于 GitBook、VuePress 等文档工具。```
+# 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
+  flattenOnGet?: boolean
+  apiDocs?: ApiDocsConfig
+}
+```
+
+### 字段说明
+
+| 字段                 | 类型                                | 默认值       | 说明                                                                                                                                   |
+| -------------------- | ----------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `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: {...} }` |
+| `flattenOnGet`       | `boolean`                           | `false`      | GET 请求专用展平：将所有 body/query/path 中的 `$ref` 参数展开为顶层交叉类型，彻底消除嵌套。详见 [GET 参数展平](#get-参数展平)            |
+| `apiDocs`            | `ApiDocsConfig`                     | 见说明       | 自动生成 API 文档（HTML/Markdown），详细配置见 [API 文档生成](#api-文档生成)                                                         |
+
+### 函数名生成规则
+
+默认函数名格式为 `{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' })
+```
+
+### 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 文档：
+
+```ts
+export default {
+  // ... 其他配置
+  apiDocs: {
+    enable: true,
+    format: 'html',           // 'html' 或 'markdown'
+    output: 'api-docs.html',  // 输出文件名
+    title: '我的 API 文档',    // 文档标题，默认取 OpenAPI info.title
+    companyName: 'XX 公司',   // 封面公司名称（仅 HTML）
+    template: './my-template.html', // 自定义 HTML 模板路径（仅 HTML）
+    theme: './my-theme.css',  // 自定义样式文件路径（仅 HTML）
+  },
+}
+```
+
+| 配置项        | 类型                        | 默认值                  | 说明                                                           |
+| ------------- | --------------------------- | ----------------------- | -------------------------------------------------------------- |
+| `enable`      | `boolean`                   | `false`                 | 是否开启文档生成                                               |
+| `format`      | `'html' \| 'markdown'`      | `'html'`                | 输出格式：HTML 适合浏览器打印为 PDF，Markdown 适合仓库内查看   |
+| `output`      | `string`                    | `'api-docs.html'`       | 输出文件名，相对 `outputDir`                                   |
+| `title`       | `string`                    | OpenAPI `info.title`    | 文档标题                                                       |
+| `companyName` | `string`                    | 无                      | 封面上的公司名称（仅 HTML）                                    |
+| `template`    | `string`                    | 内置模板                | 自定义 HTML 模板路径（仅 HTML）。优先级：`template` 配置 > 项目根目录 `.swagger.docs.html` > 内置默认模板 |
+| `theme`       | `string`                    | 无                      | 自定义 CSS 文件路径，覆盖文档样式（仅 HTML）                   |
+
+#### HTML 文档
+
+输出为带书本风格的 HTML 页面，包含：
+- **封面页**：A4 整页，显示公司名称（如配置）、API 名称和版本号
+- **目录**：方法 + 路径 | 点线 | 摘要，点击跳转到对应接口
+- **接口卡片**：包含路径参数、查询参数、请求体、响应体的字段表格（名称 / 类型 / 必填 / 描述）
+
+可通过项目根目录的 `.swagger.docs.html` 文件自定义文档样式。如果设置了 `apiDocs.template`，则优先使用该路径的模板文件。
+
+#### Markdown 文档
+
+输出为 `.md` 文件，包含：
+- 封面区域：公司名称（如配置）、API 名称和版本号
+- 目录（Table of Contents）：所有接口的锚点链接列表
+- 每个接口的详细说明：HTTP 方法 + 路径、描述、参数表格和响应表格
+
+适合直接在代码仓库中查看或用于 GitBook、VuePress 等文档工具。```

package/dist/{chunk-GTJIYNPK.js → chunk-4K4VW2PJ.js}

@@ -1,7 +1,11 @@
 import {
+  buildDefaultMethodName,
+  buildTypeName,
+  sanitizeIdentifier,
+  sanitizeSchemaTypeName,
   schemaToTs,
   toTypePropertyName
-} from "./chunk-HBBM5HFP.js";
+} from "./chunk-EAGONRXV.js";
 
 // src/generate.ts
 import path4 from "path";
@@ -52,6 +56,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,
@@ -160,28 +165,6 @@ function groupByController(operations) {
   }, {});
 }
 
-// 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("");
-}
-function sanitizePathSegment(value) {
-  return value.replace(/^\//, "").replace(/\{|\}/g, "").replace(/[^a-zA-Z0-9/_-]/g, "").replace(/\/+/g, "/");
-}
-function sanitizeIdentifier(value) {
-  const normalized = value.replace(/[^a-zA-Z0-9_$]+/g, "_").replace(/_+/g, "_").replace(/^_+|_+$/g, "");
-  if (!normalized) {
-    return "generated_api";
-  }
-  return /^[0-9]/.test(normalized) ? `api_${normalized}` : normalized;
-}
-function buildDefaultMethodName(apiPath, method) {
-  const cleaned = sanitizePathSegment(apiPath).replace(/\//g, "_").replace(/_+/g, "_");
-  return sanitizeIdentifier([method.toLowerCase(), cleaned || "root"].join("_"));
-}
-function buildTypeName(functionName, suffix) {
-  return `${toPascalCase(functionName)}${suffix}`;
-}
-
 // src/core/parsePaths.ts
 var HTTP_METHODS = ["get", "post", "put", "patch", "delete", "options", "head"];
 function collectReferencedTypeNames(schema, collected = /* @__PURE__ */ new Set()) {
@@ -191,7 +174,7 @@ function collectReferencedTypeNames(schema, collected = /* @__PURE__ */ new Set(
   if (schema.$ref) {
     const typeName = schema.$ref.split("/").pop();
     if (typeName) {
-      collected.add(typeName);
+      collected.add(sanitizeSchemaTypeName(typeName));
     }
   }
   for (const child of schema.anyOf ?? []) {
@@ -259,28 +242,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(`{ 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 {
-            requestTypeParts.push(`{ query: { ${queryFields.join(" ")} } }`);
+            if (config.mergeParams) {
+              requestTypeParts.push(`{ ${queryFields.join(" ")} }`);
+            } else {
+              requestTypeParts.push(`{ query: { ${queryFields.join(" ")} } }`);
+            }
           }
         }
       }
@@ -369,18 +384,19 @@ 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 hasBodySchema = Boolean(operation.requestBodySchema);
-  const needsCleanData = mergeParams && hasBodySchema && operation.pathParams.length > 0;
+  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" : mergeParams ? "params" : bodyOnly ? "params" : "params?.body";
+  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},
 `;
@@ -391,19 +407,20 @@ ${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 hasBodySchema = Boolean(operation.requestBodySchema);
-  const needsCleanData = mergeParams && hasBodySchema && operation.pathParams.length > 0;
+  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" : mergeParams ? "params" : bodyOnly ? "params" : "params?.body";
+  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 pathLine = operation.pathParams.length ? `    url: buildUrl(${pathArg}),
 ` : `    url: ${JSON.stringify(operation.requestPath)},
 `;
@@ -426,7 +443,7 @@ ${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) {
@@ -437,7 +454,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.
@@ -461,20 +478,21 @@ 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 hasBodySchema = Boolean(operation.requestBodySchema);
-  const needsCleanData = mergeParams && hasBodySchema && operation.pathParams.length > 0;
+  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" : mergeParams ? "params" : bodyOnly ? "params" : "params?.body";
+  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},
 `;
@@ -485,7 +503,7 @@ ${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
   );
@@ -501,10 +519,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);
@@ -519,7 +537,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)};
@@ -592,7 +610,7 @@ function renderOperationTypes(operation) {
 }
 function renderComponentSchemas(document) {
   return Object.entries(document.components?.schemas ?? {}).map(([name, schema]) => {
-    return renderComponentSchema(name, schema);
+    return renderComponentSchema(sanitizeSchemaTypeName(name), schema);
   });
 }
 function toJSDocType(typeText) {
@@ -609,7 +627,7 @@ function generateTypesFile(documentMap, operations, config) {
       const moduleName = config.moduleName?.(docUrl) ?? "services";
       parts2.push(`// Types from ${moduleName}`);
       for (const [name, schema] of Object.entries(document.components?.schemas ?? {})) {
-        parts2.push(`/** @typedef {${toJSDocType(schemaToTs(schema))}} ${name} */`);
+        parts2.push(`/** @typedef {${toJSDocType(schemaToTs(schema))}} ${sanitizeSchemaTypeName(name)} */`);
       }
     }
     for (const operation of operations) {
@@ -743,7 +761,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;
         }
@@ -754,7 +772,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);
       }
@@ -774,10 +792,10 @@ async function generateFromConfig(cwd = process.cwd()) {
     let content;
     const docFile = path4.join(cwd, config.outputDir, config.apiDocs.output);
     if (config.apiDocs.format === "markdown") {
-      const { generateApiDocsMd } = await import("./genApiDocsMd-WVDJY3ST.js");
+      const { generateApiDocsMd } = await import("./genApiDocsMd-UOK4S7BK.js");
       content = generateApiDocsMd(documentMap, operations, config);
     } else {
-      const { generateApiDocsHtml, DEFAULT_TEMPLATE } = await import("./genApiDocsHtml-V7PDR4PW.js");
+      const { generateApiDocsHtml, DEFAULT_TEMPLATE } = await import("./genApiDocsHtml-ZM2XY5P2.js");
       const templateFile = path4.join(cwd, ".swagger.docs.html");
       if (!existsSync2(templateFile)) {
         await writeTextFile(templateFile, DEFAULT_TEMPLATE);

package/dist/{chunk-HBBM5HFP.js → chunk-EAGONRXV.js}

@@ -1,10 +1,50 @@
+// src/utils/naming.ts
+import { pinyin } from "pinyin-pro";
+function toPascalCase(value) {
+  return value.split(/[^a-zA-Z0-9]+/).filter(Boolean).map((segment) => segment[0].toUpperCase() + segment.slice(1)).join("");
+}
+function sanitizePathSegment(value) {
+  return value.replace(/^\//, "").replace(/\{|\}/g, "").replace(/[^a-zA-Z0-9/_-]/g, "").replace(/\/+/g, "/");
+}
+function sanitizeIdentifier(value) {
+  const normalized = value.replace(/[^a-zA-Z0-9_$]+/g, "_").replace(/_+/g, "_").replace(/^_+|_+$/g, "");
+  if (!normalized) {
+    return "generated_api";
+  }
+  return /^[0-9]/.test(normalized) ? `api_${normalized}` : normalized;
+}
+function buildDefaultMethodName(apiPath, method) {
+  const cleaned = sanitizePathSegment(apiPath).replace(/\//g, "_").replace(/_+/g, "_");
+  return sanitizeIdentifier([method.toLowerCase(), cleaned || "root"].join("_"));
+}
+function buildTypeName(functionName, suffix) {
+  return `${toPascalCase(functionName)}${suffix}`;
+}
+function sanitizeSchemaTypeName(raw) {
+  let result = "";
+  for (const ch of raw) {
+    if ("\xAB\xBB\uFF08\uFF09()".includes(ch)) {
+      result += "_";
+    } else if (/[一-鿿]/.test(ch)) {
+      const py = pinyin(ch, { toneType: "none" });
+      result += py[0].toUpperCase() + py.slice(1);
+    } else {
+      result += ch;
+    }
+  }
+  result = result.replace(/[^A-Za-z0-9_]/g, "");
+  result = result.replace(/_+/g, "_").replace(/^_+|_+$/g, "");
+  return result || "GeneratedType";
+}
+
 // 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";
+  const raw = parts[parts.length - 1] || "unknown";
+  return sanitizeSchemaTypeName(raw);
 }
 function schemaToTs(schema) {
   if (!schema) {
@@ -59,6 +99,10 @@ function toTypePropertyName(name) {
 }
 
 export {
+  sanitizeIdentifier,
+  buildDefaultMethodName,
+  buildTypeName,
+  sanitizeSchemaTypeName,
   schemaToTs,
   toTypePropertyName
 };

package/dist/cli.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import {
   generateFromConfig
-} from "./chunk-GTJIYNPK.js";
-import "./chunk-HBBM5HFP.js";
+} from "./chunk-4K4VW2PJ.js";
+import "./chunk-EAGONRXV.js";
 
 // src/cli.ts
 async function main() {

package/dist/{genApiDocsHtml-V7PDR4PW.js → genApiDocsHtml-ZM2XY5P2.js}

@@ -1,6 +1,6 @@
 import {
   schemaToTs
-} from "./chunk-HBBM5HFP.js";
+} from "./chunk-EAGONRXV.js";
 
 // src/generators/genApiDocsHtml.ts
 function getMethodColor(method) {

package/dist/{genApiDocsMd-WVDJY3ST.js → genApiDocsMd-UOK4S7BK.js}

@@ -1,6 +1,6 @@
 import {
   schemaToTs
-} from "./chunk-HBBM5HFP.js";
+} from "./chunk-EAGONRXV.js";
 
 // src/generators/genApiDocsMd.ts
 function paramTypeDisplay(schema) {

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,7 +1,7 @@
 import {
   generateFromConfig
-} from "./chunk-GTJIYNPK.js";
-import "./chunk-HBBM5HFP.js";
+} from "./chunk-4K4VW2PJ.js";
+import "./chunk-EAGONRXV.js";
 export {
   generateFromConfig
 };

package/package.json

@@ -1,42 +1,43 @@
-{
-  "name": "swgto-ts",
-  "version": "3.0.2",
-  "description": "Generate API request files from OpenAPI 3.x documents.",
-  "license": "MIT",
-  "type": "module",
-  "bin": {
-    "swgto": "./dist/cli.js"
-  },
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
-  "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": "tsx ./src/cli.ts"
-  },
-  "keywords": [
-    "openapi",
-    "swagger",
-    "typescript",
-    "generator",
-    "cli"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "dependencies": {
-    "jiti": "^2.4.2",
-    "ts-node": "^10.9.2",
-    "tsx": "^4.21.0"
-  },
-  "devDependencies": {
-    "@types/node": "^24.6.0",
-    "tsup": "^8.5.0",
-    "typescript": "^5.9.3",
-    "vitest": "^3.2.4"
-  }
-}
+{
+  "name": "swgto-ts",
+  "version": "3.2.0",
+  "description": "Generate API request files from OpenAPI 3.x documents.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "swgto": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "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": "tsx ./src/cli.ts"
+  },
+  "keywords": [
+    "openapi",
+    "swagger",
+    "typescript",
+    "generator",
+    "cli"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "jiti": "^2.4.2",
+    "pinyin-pro": "^3.29.4",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.21.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  }
+}