swagger2api-v3 1.1.9 → 1.1.11

package/README.md

@@ -2,11 +2,11 @@
 
 English | [中文](./README_CN.md)
 
-A powerful command-line tool for automatically generating TypeScript or JavaScript interface code from OpenAPI 3.x / Swagger 3.0 documentation.
+A powerful command-line tool for automatically generating TypeScript or JavaScript interface code from OpenAPI 3.0 documentation.
 
 ## ✨ Features
 
-- 🚀 **Fast Generation** - Quickly generate TypeScript interface code from OpenAPI/Swagger 3.0 JSON
+- 🚀 **Fast Generation** - Quickly generate TypeScript interface code from OpenAPI 3.0 JSON or YAML
 - 📁 **Smart Grouping** - Support automatic file grouping by document tags
 - 📝 **Detailed Comments** - Automatically generate detailed comments including descriptions, parameters, and return values
 - 🎨 **Code Formatting** - Support custom formatting commands
@@ -44,6 +44,7 @@ The tool generates a `.swagger.config.json` configuration file:
   "generator": "typescript",
   "requestStyle": "generic",
   "groupByTags": true,
+  "multiTagStrategy": "first",
   "overwrite": true,
   "prefix": "",
   "lint": "prettier --write",
@@ -75,10 +76,11 @@ npx swagger2api-v3 generate
 | Option                   | Type                  | Default        | Description                                                                                                                                                        |
 | ------------------------ | --------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `$schema`                | string                | -              | Local JSON Schema path for editor completion. The default points to `node_modules/swagger2api-v3/dist/.swagger2api.schema.json`                                    |
-| `input`                  | string                | -              | OpenAPI/Swagger 3.0 JSON file path or URL                                                                                                                          |
+| `input`                  | string                | -              | OpenAPI 3.0 JSON/YAML file path or URL; local and remote external `$ref` references are bundled automatically                                                      |
 | `output`                 | string                | `'./src/api'`  | Output directory for generated code                                                                                                                                |
 | `generator`              | string                | `'typescript'` | Code generator type. Supports `'typescript'` and `'javascript'`. `'javascript'` outputs `.js` files and skips type file generation                                 |
 | `groupByTags`            | boolean               | `true`         | Whether to group files by tags                                                                                                                                     |
+| `multiTagStrategy`       | 'first' \| 'all'      | `'first'`      | Grouping strategy for operations with multiple tags. `first` uses only the first tag, `all` combines all tags into one group name                                  |
 | `overwrite`              | boolean               | `true`         | Whether to overwrite existing files                                                                                                                                |
 | `prefix`                 | string                | `''`           | Common prefix for API paths                                                                                                                                        |
 | `importTemplate`         | string                | -              | Import statement template for request function                                                                                                                     |

package/dist/.swagger2api.schema.json

@@ -10,11 +10,11 @@
     },
     "input": {
       "type": "string",
-      "description": "OpenAPI JSON 文件路径或 URL"
+      "description": "OpenAPI 3.0 JSON/YAML 文件路径或 URL"
     },
     "output": {
       "type": "string",
-      "description": "生成代码输出目录"
+      "description": "生成代码输出目录，不能是当前工作目录或其父目录"
     },
     "generator": {
       "enum": ["typescript", "javascript"],
@@ -24,6 +24,10 @@
       "type": "boolean",
       "description": "是否按 tags 分组生成文件"
     },
+    "multiTagStrategy": {
+      "enum": ["first", "all"],
+      "description": "多 tag 接口分组策略。first 只使用第一个 tag，all 将所有 tags 合成一个分组"
+    },
     "overwrite": {
       "type": "boolean",
       "description": "生成前是否覆盖输出目录"

package/dist/cli/index.js

@@ -38,12 +38,13 @@ const commander_1 = require("commander");
 const path = __importStar(require("path"));
 const fs = __importStar(require("fs"));
 const index_1 = require("../index");
+const utils_1 = require("../utils");
 const program = new commander_1.Command();
 // 版本信息
 const packageJson = JSON.parse(fs.readFileSync(path.join(__dirname, '../../package.json'), 'utf-8'));
 program
     .name('swagger2api-v3')
-    .description('从 Swagger/OpenAPI 文档生成 TypeScript API 接口')
+    .description('从 OpenAPI 3.0 文档生成 TypeScript API 接口')
     .version(packageJson.version);
 // generate 命令
 program
@@ -51,7 +52,7 @@ program
     .alias('gen')
     .description('根据配置文件生成 API 接口')
     .option('-c, --config <path>', '配置文件路径', '.swagger.config.json')
-    .option('-i, --input <path>', 'Swagger JSON 文件路径或 URL')
+    .option('-i, --input <path>', 'OpenAPI JSON/YAML 文件路径或 URL')
     .option('-o, --output <path>', '输出目录')
     .option('--no-types', '不生成类型文件')
     .option('--no-group', '不按标签分组')
@@ -73,7 +74,7 @@ program
                     prettify: true
                 }
             };
-            const { generate } = await Promise.resolve().then(() => __importStar(require('../index')));
+            const { generate } = await import('../index.js');
             await generate(config);
         }
         else {
@@ -82,7 +83,7 @@ program
         }
     }
     catch (error) {
-        console.error('❌ 生成失败:', error);
+        utils_1.logger.error('生成失败', error);
         process.exit(1);
     }
 });
@@ -98,11 +99,11 @@ program
         const config = createInitConfig(configPath, options.force);
         const successMessage = getInitSuccessMessage(existsBeforeInit, options.force);
         fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
-        console.log(successMessage, configPath);
-        console.log('💡 请根据需要修改配置文件，然后运行 swagger2api-v3 generate');
+        utils_1.logger.success(`${successMessage} ${configPath}`);
+        utils_1.logger.info('请根据需要修改配置文件，然后运行 swagger2api-v3 generate');
     }
     catch (error) {
-        console.error('❌ 创建配置文件失败:', error);
+        utils_1.logger.error('创建配置文件失败', error);
         process.exit(1);
     }
 });
@@ -115,29 +116,28 @@ program
     const configPath = path.resolve(process.cwd(), options.config);
     try {
         if (!fs.existsSync(configPath)) {
-            console.error(`❌ 找不到配置文件: ${configPath}`);
+            utils_1.logger.error(`找不到配置文件: ${configPath}`);
             process.exit(1);
         }
         const configContent = fs.readFileSync(configPath, 'utf-8');
         const config = JSON.parse(configContent);
-        const { validateSwaggerConfig } = await Promise.resolve().then(() => __importStar(require('../config/validator')));
+        const { validateSwaggerConfig } = await import('../config/validator.js');
         const errors = validateSwaggerConfig(config);
         if (errors.length === 0) {
-            console.log('✅ 配置文件验证通过');
+            utils_1.logger.success('配置文件验证通过');
         }
         else {
-            console.error('❌ 配置验证失败:');
-            errors.forEach((error) => console.error(`   - ${error}`));
+            utils_1.logger.errorList('配置验证失败:', errors);
             process.exit(1);
         }
     }
     catch (error) {
         if (error instanceof SyntaxError) {
-            console.error(`❌ 配置文件 JSON 格式错误: ${configPath}`);
-            console.error('错误详情:', error.message);
+            utils_1.logger.error(`配置文件 JSON 格式错误: ${configPath}`);
+            utils_1.logger.error(`错误详情: ${error.message}`);
         }
         else {
-            console.error('❌ 配置文件验证失败:', error);
+            utils_1.logger.error('配置文件验证失败', error);
         }
         process.exit(1);
     }
@@ -175,6 +175,7 @@ function createDefaultConfig() {
         generator: 'typescript',
         requestStyle: 'generic',
         groupByTags: true,
+        multiTagStrategy: 'first',
         overwrite: true,
         prefix: '',
         lint: 'prettier --write',
@@ -202,12 +203,12 @@ function createDefaultConfig() {
  */
 function getInitSuccessMessage(existsBeforeInit, force) {
     if (existsBeforeInit && force) {
-        return '✅ 配置文件已覆盖:';
+        return '配置文件已覆盖:';
     }
     if (existsBeforeInit) {
-        return '✅ 配置文件已补全:';
+        return '配置文件已补全:';
     }
-    return '✅ 配置文件已创建:';
+    return '配置文件已创建:';
 }
 /**
  * 读取已存在的配置文件
@@ -221,11 +222,11 @@ function readExistingConfig(configPath) {
     }
     catch (error) {
         if (error instanceof SyntaxError) {
-            console.error(`❌ 配置文件 JSON 格式错误: ${configPath}`);
-            console.error('错误详情:', error.message);
+            utils_1.logger.error(`配置文件 JSON 格式错误: ${configPath}`);
+            utils_1.logger.error(`错误详情: ${error.message}`);
         }
         else {
-            console.error('❌ 读取配置文件失败:', error);
+            utils_1.logger.error('读取配置文件失败', error);
         }
         process.exit(1);
         throw error;

package/dist/config/validator.js

@@ -1,12 +1,48 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateSwaggerConfig = validateSwaggerConfig;
+const path = __importStar(require("path"));
+const file_1 = require("../utils/file");
 const CONFIG_KEYS = [
     '$schema',
     'input',
     'output',
     'generator',
     'groupByTags',
+    'multiTagStrategy',
     'overwrite',
     'prefix',
     'requestStyle',
@@ -42,10 +78,15 @@ const COMMENT_KEYS = [
  */
 function validateSwaggerConfig(config) {
     const errors = [];
+    if (!isPlainObject(config)) {
+        return ['config 必须是对象'];
+    }
     validateRequiredString(config.input, 'input', errors);
     validateRequiredString(config.output, 'output', errors);
+    validateOutputPath(config.output, errors);
     validateEnum(config.generator, 'generator', ['typescript', 'javascript'], errors);
     validateBoolean(config.groupByTags, 'groupByTags', errors);
+    validateOptionalEnum(config.multiTagStrategy, 'multiTagStrategy', ['first', 'all'], errors);
     validateOptionalBoolean(config.overwrite, 'overwrite', errors);
     validateOptionalString(config.prefix, 'prefix', errors);
     validateOptionalString(config.importTemplate, 'importTemplate', errors);
@@ -69,10 +110,25 @@ function validateSwaggerConfig(config) {
  * @param errors 错误信息数组
  */
 function validateRequiredString(value, field, errors) {
-    if (typeof value !== 'string' || !value) {
+    if (typeof value !== 'string' || !value.trim()) {
         errors.push(`${field} 配置项不能为空，且必须是字符串`);
     }
 }
+/**
+ * 验证输出路径不会覆盖当前工作目录或其父目录
+ * @param value 输出路径
+ * @param errors 错误信息数组
+ */
+function validateOutputPath(value, errors) {
+    if (typeof value !== 'string' || !value.trim())
+        return;
+    const currentDirectory = path.resolve(process.cwd());
+    const outputDirectory = path.resolve(currentDirectory, value);
+    if (outputDirectory === currentDirectory ||
+        (0, file_1.isPathInside)(outputDirectory, currentDirectory)) {
+        errors.push('output 不能是当前工作目录或其父目录');
+    }
+}
 /**
  * 验证可选字符串
  * @param value 字段值
@@ -149,13 +205,17 @@ function validateStringArray(value, field, errors) {
  * @param errors 错误信息数组
  */
 function validateFilter(config, errors) {
-    if (!config.filter)
+    if (!validateOptionalPlainObject(config.filter, 'filter', errors))
         return;
     validateKnownKeys(config.filter, ['include', 'exclude'], 'filter', errors);
-    validateKnownKeys(config.filter.include, ['tags'], 'filter.include', errors);
-    validateKnownKeys(config.filter.exclude, ['tags'], 'filter.exclude', errors);
-    validateStringArray(config.filter.include?.tags, 'filter.include.tags', errors);
-    validateStringArray(config.filter.exclude?.tags, 'filter.exclude.tags', errors);
+    if (validateOptionalPlainObject(config.filter.include, 'filter.include', errors)) {
+        validateKnownKeys(config.filter.include, ['tags'], 'filter.include', errors);
+        validateStringArray(config.filter.include.tags, 'filter.include.tags', errors);
+    }
+    if (validateOptionalPlainObject(config.filter.exclude, 'filter.exclude', errors)) {
+        validateKnownKeys(config.filter.exclude, ['tags'], 'filter.exclude', errors);
+        validateStringArray(config.filter.exclude.tags, 'filter.exclude.tags', errors);
+    }
 }
 /**
  * 验证生成选项配置
@@ -163,7 +223,7 @@ function validateFilter(config, errors) {
  * @param errors 错误信息数组
  */
 function validateOptions(config, errors) {
-    if (!config.options)
+    if (!validateOptionalPlainObject(config.options, 'options', errors))
         return;
     validateKnownKeys(config.options, OPTIONS_KEYS, 'options', errors);
     validateOptionalBoolean(config.options.generateModels, 'options.generateModels', errors);
@@ -179,8 +239,9 @@ function validateOptions(config, errors) {
  * @param errors 错误信息数组
  */
 function validateTagGrouping(config, errors) {
-    if (!config.tagGrouping)
+    if (!validateOptionalPlainObject(config.tagGrouping, 'tagGrouping', errors)) {
         return;
+    }
     validateKnownKeys(config.tagGrouping, TAG_GROUPING_KEYS, 'tagGrouping', errors);
     validateOptionalBoolean(config.tagGrouping.enabled, 'tagGrouping.enabled', errors);
     validateOptionalBoolean(config.tagGrouping.createSubDirectories, 'tagGrouping.createSubDirectories', errors);
@@ -192,7 +253,7 @@ function validateTagGrouping(config, errors) {
  * @param errors 错误信息数组
  */
 function validateComments(config, errors) {
-    if (!config.comments)
+    if (!validateOptionalPlainObject(config.comments, 'comments', errors))
         return;
     validateKnownKeys(config.comments, COMMENT_KEYS, 'comments', errors);
     validateOptionalBoolean(config.comments.includeDescription, 'comments.includeDescription', errors);
@@ -216,3 +277,27 @@ function validateKnownKeys(value, knownKeys, path, errors) {
         }
     }
 }
+/**
+ * 验证可选配置值是否为普通对象
+ * @param value 配置值
+ * @param field 字段路径
+ * @param errors 错误信息数组
+ * @returns 配置值是否为普通对象
+ */
+function validateOptionalPlainObject(value, field, errors) {
+    if (value === undefined)
+        return false;
+    if (!isPlainObject(value)) {
+        errors.push(`${field} 必须是对象`);
+        return false;
+    }
+    return true;
+}
+/**
+ * 判断值是否为普通对象
+ * @param value 待判断的值
+ * @returns 是否为普通对象
+ */
+function isPlainObject(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}

package/dist/core/generator.d.ts

@@ -4,6 +4,11 @@ import { SwaggerConfig, ApiInfo, TypeInfo } from '../types';
  */
 export declare class CodeGenerator {
     private config;
+    private readonly outputRoot;
+    /**
+     * 创建代码生成器
+     * @param config 生成配置
+     */
     constructor(config: SwaggerConfig);
     /**
      * 生成所有文件
@@ -23,6 +28,31 @@ export declare class CodeGenerator {
      * @returns 类型文件内容
      */
     private generateTypesContent;
+    /**
+     * 渲染类型定义列表
+     * @param types 类型定义数组
+     * @returns 类型定义内容
+     */
+    private renderTypeDefinitions;
+    /**
+     * 合并类型定义
+     * @param modelTypes 组件模型类型
+     * @param parameterTypes 查询参数类型
+     * @returns 合并后的类型定义
+     */
+    private mergeTypeDefinitions;
+    /**
+     * 判断是否应提取查询参数类型
+     * @returns 是否提取查询参数类型
+     */
+    private shouldExtractQueryParameterTypes;
+    /**
+     * 生成 tag 内的查询参数类型文件
+     * @param folderName tag 目录名
+     * @param apis 当前 tag 的 API 接口
+     * @param modelTypes 组件模型类型
+     */
+    private generateTagParameterTypesFile;
     /**
      * 按标签生成API文件
      * @param groupedApis 按标签分组的API
@@ -46,25 +76,35 @@ export declare class CodeGenerator {
     /**
      * 生成单个API函数
      * @param api API接口信息
+     * @param queryParameterTypeName 查询参数类型名
      * @returns API函数代码
      */
     private generateApiFunction;
     /**
      * 生成直接参数形式
      * @param parameters OpenAPI 参数数组
+     * @param isJavaScript 是否生成 JavaScript 参数
+     * @param queryParameterTypeName 查询参数类型名
      * @returns 函数参数字符串
      */
     private generateDirectParameters;
     /**
-     * 从schema获取类型
-     * @param schema Swagger schema
-     * @returns 类型字符串
+     * 获取当前配置下可安全输出的类型
+     * @param type 类型字符串
+     * @returns 安全类型字符串
      */
-    private getTypeFromSchema;
+    private getSafeGeneratedType;
+    /**
+     * 渲染内联查询参数类型成员
+     * @param parameters 查询参数数组
+     * @returns 内联类型成员
+     */
+    private renderInlineQueryParameterMembers;
     /**
      * 收集API数组中实际使用的类型
      * @param apis API接口数组
      * @param definedTypes 已定义的类型数组
+     * @param excludeQueryParameters 是否排除查询参数
      * @returns 使用的类型名称数组
      */
     private collectUsedTypes;
@@ -80,30 +120,62 @@ export declare class CodeGenerator {
      * @returns 是否为基础类型
      */
     private isPrimitiveType;
-    /**
-     * 检测是否为通用响应容器类型
-     * @param type 类型信息
-     * @param definition 类型定义
-     * @returns 是否为通用响应容器类型
-     */
-    private isGenericResponseContainer;
     /**
      * 生成请求配置
      * @param api API接口信息
      * @returns 请求配置代码
      */
     private generateRequestConfig;
+    /**
+     * 创建不重复的路径参数变量名
+     * @param parameters OpenAPI 路径参数
+     * @returns 路径参数变量名
+     */
+    private createPathParameterNames;
     /**
      * 生成入口文件
      * @param groupedApis 按标签分组的API
      */
     private generateIndexFile;
+    /**
+     * 校验输出目录不会覆盖当前工作目录或其父目录
+     */
+    private assertSafeOutputDirectory;
+    /**
+     * 解析并校验输出目录内的文件路径
+     * @param segments 输出目录下的路径片段
+     * @returns 安全的绝对路径
+     */
+    private resolveOutputPath;
+    /**
+     * 写入生成文件，overwrite=false 时保留已存在文件
+     * @param filePath 文件路径
+     * @param content 文件内容
+     */
+    private writeGeneratedFile;
     /**
      * 获取标签对应的文件名
      * @param tag 标签名
      * @returns 文件名
      */
     private getTagFileName;
+    /**
+     * 校验所有标签生成的目录名称安全且不重复
+     * @param groupedApis 按标签分组的 API
+     */
+    private validateTagFolders;
+    /**
+     * 转义模板字符串中的特殊字符
+     * @param value 原始字符串
+     * @returns 可安全写入模板字符串的内容
+     */
+    private escapeTemplateLiteral;
+    /**
+     * 将字符串转换为安全的单引号字面量
+     * @param value 原始字符串
+     * @returns 单引号字符串字面量
+     */
+    private toSingleQuotedString;
     /**
      * 生成文件头部注释
      * @param defaultHeader 默认头部注释