swgto-ts 2.0.0 → 2.0.1

package/README.md

@@ -1,147 +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/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' })
-```
+# 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-4OK6R2K5.js → chunk-ZURWUVPF.js}

@@ -1,5 +1,5 @@
 // src/generate.ts
-import path3 from "path";
+import path4 from "path";
 
 // src/config/loadConfig.ts
 import { existsSync } from "fs";
@@ -74,8 +74,8 @@ function getPathMethods(operations) {
   }
   return map;
 }
-function deriveControllerName(path4, allPaths, pathMethods) {
-  const segments = path4.split("/").filter(Boolean);
+function deriveControllerName(path5, allPaths, pathMethods) {
+  const segments = path5.split("/").filter(Boolean);
   if (segments.length === 0) return "index";
   if (segments.length === 1) return segments[0];
   let effectiveLen = segments.length;
@@ -98,14 +98,14 @@ function deriveControllerName(path4, allPaths, pathMethods) {
         return segments[depth - 1];
       }
       const hasDirectSibling = [...allPaths].some((p) => {
-        if (p === path4) return false;
+        if (p === path5) 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 === path5) return false;
           if (!p.startsWith(ancestorPath + "/")) return false;
           const remaining = p.slice(ancestorPath.length + 1);
           if (remaining.includes("/")) return false;
@@ -120,7 +120,7 @@ function deriveControllerName(path4, allPaths, pathMethods) {
     }
     const currentPath = "/" + segments.slice(0, depth + 1).join("/");
     const hasChildren = [...allPaths].some(
-      (p) => p !== path4 && p.startsWith(currentPath + "/")
+      (p) => p !== path5 && p.startsWith(currentPath + "/")
     );
     if (hasChildren) {
       return resultName(segments, depth);
@@ -676,6 +676,64 @@ async function removeDir(dirPath) {
   }
 }
 
+// src/utils/snapshot.ts
+import path3 from "path";
+import { readFile, writeFile as writeFile2 } from "fs/promises";
+function buildKey(op) {
+  return `${op.docUrl}|${op.method}|${op.path}`;
+}
+function toEntry(op) {
+  return {
+    key: buildKey(op),
+    method: op.method,
+    path: op.path,
+    functionName: op.functionName,
+    summary: op.summary,
+    moduleName: op.moduleName
+  };
+}
+async function loadSnapshot(snapshotPath) {
+  const map = /* @__PURE__ */ new Map();
+  try {
+    const raw = await readFile(snapshotPath, "utf8");
+    const data = JSON.parse(raw);
+    if (data.version === 1) {
+      for (const entry of data.operations) {
+        map.set(entry.key, entry);
+      }
+    }
+  } catch {
+  }
+  return map;
+}
+async function saveSnapshot(snapshotPath, operations) {
+  const snapshot = {
+    version: 1,
+    operations: operations.map(toEntry)
+  };
+  await ensureDir(path3.dirname(snapshotPath));
+  await writeFile2(snapshotPath, JSON.stringify(snapshot, null, 2), "utf8");
+}
+function compareSnapshot(previous, current) {
+  const currentKeys = /* @__PURE__ */ new Set();
+  const newOperations = [];
+  for (const op of current) {
+    const key = buildKey(op);
+    currentKeys.add(key);
+    if (!previous.has(key)) {
+      newOperations.push(toEntry(op));
+    }
+  }
+  const removedOperations = [];
+  for (const [key, entry] of previous) {
+    if (!currentKeys.has(key)) {
+      removedOperations.push(entry);
+    }
+  }
+  return { newOperations, removedOperations };
+}
+var SNAPSHOT_FILE = ".swaggerts.cache.json";
+
 // src/generate.ts
 function getRootImportPath(typeName) {
   return `../${typeName}`;
@@ -684,8 +742,10 @@ async function generateFromConfig(cwd = process.cwd()) {
   const { configPath, config } = await loadConfig(cwd);
   const documentMap = /* @__PURE__ */ new Map();
   const operations = [];
+  const snapshotPath = path4.join(cwd, config.outputDir, SNAPSHOT_FILE);
+  const previousSnapshot = await loadSnapshot(snapshotPath);
   if (config.cleanOutput) {
-    await removeDir(path3.join(cwd, config.outputDir));
+    await removeDir(path4.join(cwd, config.outputDir));
     console.log(`Cleaned output directory: ${config.outputDir}`);
   }
   for (const docUrl of config.docUrls) {
@@ -694,13 +754,14 @@ async function generateFromConfig(cwd = process.cwd()) {
     operations.push(...parsePaths(document, docUrl, config));
   }
   const grouped = groupByPrefix(operations);
+  const { newOperations, removedOperations } = compareSnapshot(previousSnapshot, operations);
   const files = [];
   for (const [moduleName, moduleOperations] of Object.entries(grouped)) {
     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 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);
         for (const op of controllerOperations) {
           op.fileBaseName = controllerName;
@@ -710,8 +771,8 @@ async function generateFromConfig(cwd = process.cwd()) {
       }
     } else {
       for (const operation of moduleOperations) {
-        const relativeFile = path3.join(config.outputDir, moduleName, `${operation.fileBaseName}.${config.outputType}`);
-        const absoluteFile = path3.join(cwd, relativeFile);
+        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);
         await writeTextFile(absoluteFile, content);
         files.push(relativeFile);
@@ -720,21 +781,24 @@ async function generateFromConfig(cwd = process.cwd()) {
   }
   const typesContent = generateTypesFile(documentMap, operations, config);
   const indexContent = generateIndexFile(operations, config);
-  const typesFile = path3.join(cwd, config.outputDir, `${config.typeName}.${config.outputType === "ts" ? "ts" : "js"}`);
-  const indexFile = path3.join(cwd, config.outputDir, `index.${config.outputType}`);
+  const typesFile = path4.join(cwd, config.outputDir, `${config.typeName}.${config.outputType === "ts" ? "ts" : "js"}`);
+  const indexFile = path4.join(cwd, config.outputDir, `index.${config.outputType}`);
   await writeTextFile(typesFile, typesContent);
   await writeTextFile(indexFile, indexContent);
   files.push(
-    path3.relative(cwd, typesFile),
-    path3.relative(cwd, indexFile)
+    path4.relative(cwd, typesFile),
+    path4.relative(cwd, indexFile)
   );
+  await saveSnapshot(snapshotPath, operations);
   return {
     configPath,
     files,
     operationCount: operations.length,
     moduleCount: Object.keys(grouped).length,
-    apiFileCount: files.length - 2
+    apiFileCount: files.length - 2,
     // exclude types + index
+    newOperations,
+    removedOperations
   };
 }
 

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   generateFromConfig
-} from "./chunk-4OK6R2K5.js";
+} from "./chunk-ZURWUVPF.js";
 
 // src/cli.ts
 async function main() {
@@ -13,6 +13,23 @@ async function main() {
     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.`);
+    if (result.newOperations.length > 0) {
+      console.log(`
+\u65B0\u589E ${result.newOperations.length} \u4E2A API:`);
+      const maxWidth = Math.max(...result.newOperations.map((op) => `${op.method.toUpperCase()} ${op.path}`.length));
+      for (const op of result.newOperations) {
+        const label = `${op.method.toUpperCase()} ${op.path}`.padEnd(maxWidth);
+        const desc = op.summary ? `  ${op.summary}` : "";
+        console.log(`  ${label}  -> ${op.functionName}${desc}`);
+      }
+    }
+    if (result.removedOperations.length > 0) {
+      console.log(`
+\u79FB\u9664 ${result.removedOperations.length} \u4E2A API:`);
+      for (const op of result.removedOperations) {
+        console.log(`  ${op.method.toUpperCase()} ${op.path}  (${op.functionName})`);
+      }
+    }
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     console.error(`swgto failed: ${message}`);

package/dist/index.d.ts

@@ -1,12 +1,3 @@
-interface GenerateResult {
-    configPath: string;
-    files: string[];
-    operationCount: number;
-    moduleCount: number;
-    apiFileCount: number;
-}
-declare function generateFromConfig(cwd?: string): Promise<GenerateResult>;
-
 type OutputType = 'ts' | 'js';
 type RequestConfig = Record<string, unknown>;
 interface SwaggerTsConfig {
@@ -25,4 +16,25 @@ interface SwaggerTsConfig {
     mergeParams?: boolean;
 }
 
+interface SnapshotEntry {
+    /** Unique key: docUrl | method | path */
+    key: string;
+    method: string;
+    path: string;
+    functionName: string;
+    summary?: string;
+    moduleName: string;
+}
+
+interface GenerateResult {
+    configPath: string;
+    files: string[];
+    operationCount: number;
+    moduleCount: number;
+    apiFileCount: number;
+    newOperations: SnapshotEntry[];
+    removedOperations: SnapshotEntry[];
+}
+declare function generateFromConfig(cwd?: string): Promise<GenerateResult>;
+
 export { type GenerateResult, type RequestConfig, type SwaggerTsConfig, generateFromConfig };

package/dist/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swgto-ts",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Generate API request files from OpenAPI 3.x documents.",
   "license": "MIT",
   "type": "module",