swagger2api-v3 1.1.9 → 1.1.10

package/README.md

@@ -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",
@@ -79,6 +80,7 @@ npx swagger2api-v3 generate
 | `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

@@ -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,6 +38,7 @@ 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'));
@@ -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

@@ -7,6 +7,7 @@ const CONFIG_KEYS = [
     'output',
     'generator',
     'groupByTags',
+    'multiTagStrategy',
     'overwrite',
     'prefix',
     'requestStyle',
@@ -46,6 +47,7 @@ function validateSwaggerConfig(config) {
     validateRequiredString(config.output, '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);

package/dist/core/generator.d.ts

@@ -61,6 +61,12 @@ export declare class CodeGenerator {
      * @returns 类型字符串
      */
     private getTypeFromSchema;
+    /**
+     * 获取当前配置下可安全输出的类型
+     * @param type 类型字符串
+     * @returns 安全类型字符串
+     */
+    private getSafeGeneratedType;
     /**
      * 收集API数组中实际使用的类型
      * @param apis API接口数组
@@ -93,11 +99,23 @@ export declare class CodeGenerator {
      * @returns 请求配置代码
      */
     private generateRequestConfig;
+    /**
+     * 生成 params 对象字段访问表达式
+     * @param name 参数名
+     * @returns 字段访问表达式
+     */
+    private getParamAccessExpression;
     /**
      * 生成入口文件
      * @param groupedApis 按标签分组的API
      */
     private generateIndexFile;
+    /**
+     * 写入生成文件，overwrite=false 时保留已存在文件
+     * @param filePath 文件路径
+     * @param content 文件内容
+     */
+    private writeGeneratedFile;
     /**
      * 获取标签对应的文件名
      * @param tag 标签名

package/dist/core/generator.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CodeGenerator = void 0;
 const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
 const child_process_1 = require("child_process");
 const util_1 = require("util");
 const utils_1 = require("../utils");
@@ -90,7 +91,7 @@ class CodeGenerator {
     async generateTypesFile(types) {
         const content = this.generateTypesContent(types);
         const filePath = path.join(this.config.output, 'types.ts');
-        (0, utils_1.writeFile)(filePath, content);
+        this.writeGeneratedFile(filePath, content);
     }
     /**
      * 生成类型文件内容
@@ -136,7 +137,7 @@ class CodeGenerator {
             const ext = this.config.generator === 'javascript' ? 'js' : 'ts';
             const filePath = path.join(tagFolderPath, `index.${ext}`);
             const content = this.generateApiFileContent(apis, types, tag);
-            (0, utils_1.writeFile)(filePath, content);
+            this.writeGeneratedFile(filePath, content);
         }
     }
     /**
@@ -148,7 +149,7 @@ class CodeGenerator {
         const ext = this.config.generator === 'javascript' ? 'js' : 'ts';
         const filePath = path.join(this.config.output, `api.${ext}`);
         const content = this.generateApiFileContent(apis, types);
-        (0, utils_1.writeFile)(filePath, content);
+        this.writeGeneratedFile(filePath, content);
     }
     /**
      * 生成API文件内容
@@ -200,7 +201,7 @@ class CodeGenerator {
                 type: p.type,
                 description: p.description
             }));
-            const comment = (0, utils_1.generateApiComment)({ summary: api.description, deprecated: false }, swaggerParams);
+            const comment = (0, utils_1.generateApiComment)({ summary: api.description, deprecated: api.deprecated }, swaggerParams);
             parts.push(comment);
         }
         // 生成函数签名
@@ -213,7 +214,9 @@ class CodeGenerator {
         }));
         // 生成直接参数形式
         const functionParams = this.generateDirectParameters(swaggerParameters, this.config.generator === 'javascript');
-        const responseType = api.responseType || 'any';
+        const responseType = this.config.options?.generateModels === false
+            ? 'any'
+            : api.responseType || 'any';
         const functionName = (0, utils_1.toCamelCase)(api.name);
         parts.push(`export const ${functionName} = (${functionParams}) => {`);
         // 生成请求配置
@@ -254,7 +257,8 @@ class CodeGenerator {
                 const paramType = allParams
                     .map((p) => {
                     const optional = p.required ? '' : '?';
-                    return `${p.name}${optional}: ${p.type}`;
+                    const type = this.getSafeGeneratedType(p.type);
+                    return `${(0, utils_1.formatTsPropertyName)(p.name)}${optional}: ${type}`;
                 })
                     .join(', ');
                 // 检查是否所有参数都是可选的
@@ -273,7 +277,7 @@ class CodeGenerator {
                 const bodyType = bodyParam.schema
                     ? this.getTypeFromSchema(bodyParam.schema)
                     : bodyParam.type;
-                params.push(`data: ${bodyType}`);
+                params.push(`data: ${this.getSafeGeneratedType(bodyType)}`);
             }
         }
         // 添加可选的config参数
@@ -286,8 +290,23 @@ class CodeGenerator {
      * @returns 类型字符串
      */
     getTypeFromSchema(schema) {
+        if (this.config.options?.generateModels === false) {
+            return 'any';
+        }
         return (0, utils_1.swaggerTypeToTsType)(schema);
     }
+    /**
+     * 获取当前配置下可安全输出的类型
+     * @param type 类型字符串
+     * @returns 安全类型字符串
+     */
+    getSafeGeneratedType(type) {
+        if (!type)
+            return 'any';
+        if (this.config.options?.generateModels !== false)
+            return type;
+        return this.isPrimitiveType(type) ? type : 'any';
+    }
     /**
      * 收集API数组中实际使用的类型
      * @param apis API接口数组
@@ -409,8 +428,14 @@ class CodeGenerator {
         }
         // 查询参数和路径参数都从params对象中获取
         if (queryParams.length > 0) {
-            // 直接传递params对象，让axios自动过滤undefined值
-            config.push('params');
+            if (pathParams.length > 0) {
+                const queryEntries = queryParams.map((param) => `${JSON.stringify(param.name)}: ${this.getParamAccessExpression(param.name)}`);
+                config.push(`params: { ${queryEntries.join(', ')} }`);
+            }
+            else {
+                // 直接传递params对象，让axios自动过滤undefined值
+                config.push('params');
+            }
         }
         // 请求体数据
         const bodyParams = api.parameters.filter((p) => p.in === 'body');
@@ -425,6 +450,16 @@ class CodeGenerator {
         config.push('...config');
         return `{\n    ${config.join(',\n    ')}\n  }`;
     }
+    /**
+     * 生成 params 对象字段访问表达式
+     * @param name 参数名
+     * @returns 字段访问表达式
+     */
+    getParamAccessExpression(name) {
+        return (0, utils_1.isValidIdentifier)(name)
+            ? `params.${name}`
+            : `params[${JSON.stringify(name)}]`;
+    }
     /**
      * 生成入口文件
      * @param groupedApis 按标签分组的API
@@ -452,6 +487,17 @@ class CodeGenerator {
         const content = [this.generateHeader(), '', ...exports, ''].join('\n');
         const ext = this.config.generator === 'javascript' ? 'js' : 'ts';
         const filePath = path.join(this.config.output, `index.${ext}`);
+        this.writeGeneratedFile(filePath, content);
+    }
+    /**
+     * 写入生成文件，overwrite=false 时保留已存在文件
+     * @param filePath 文件路径
+     * @param content 文件内容
+     */
+    writeGeneratedFile(filePath, content) {
+        if (this.config.overwrite === false && fs.existsSync(filePath)) {
+            return;
+        }
         (0, utils_1.writeFile)(filePath, content);
     }
     /**
@@ -492,15 +538,15 @@ class CodeGenerator {
         if (!this.config.lint)
             return;
         try {
-            console.log(`🎨 Running lint command: ${this.config.lint} ${this.config.output}`);
+            utils_1.logger.info(`执行 Lint 命令: ${this.config.lint} ${this.config.output}`);
             const result = await execPromise(`${this.config.lint} ${this.config.output}`);
             if (result.stdout) {
-                console.log(result.stdout);
+                utils_1.logger.info(result.stdout.trim());
             }
-            console.log('✅ Lint completed successfully');
+            utils_1.logger.success('Lint 执行完成');
         }
         catch (error) {
-            console.warn(`⚠️  Failed to run lint command:`, error.message);
+            utils_1.logger.warn(`Lint 命令执行失败: ${error.message}`);
         }
     }
 }

package/dist/core/parser.d.ts

@@ -51,6 +51,12 @@ export declare class SwaggerParser {
      * @returns 引用解析后的对象
      */
     private resolveReference;
+    /**
+     * 合并同名同位置参数，后出现的 operation 级参数覆盖 path 级参数
+     * @param parameters 参数数组
+     * @returns 合并后的参数数组
+     */
+    private mergeParameters;
     /**
      * 按标签分组API
      * @param apis API接口数组

package/dist/core/parser.js

@@ -11,6 +11,7 @@ const HTTP_METHODS = [
     'head',
     'options'
 ];
+const MAX_REF_RESOLVE_DEPTH = 20;
 /**
  * Swagger文档解析器
  */
@@ -54,10 +55,7 @@ class SwaggerParser {
      */
     parseOperation(method, path, operation, globalParameters) {
         // 合并全局参数和操作参数
-        const allParameters = [
-            ...(globalParameters || []),
-            ...(operation.parameters || [])
-        ].map((parameter) => this.resolveReference(parameter));
+        const allParameters = this.mergeParameters([...(globalParameters || []), ...(operation.parameters || [])].map((parameter) => this.resolveReference(parameter)));
         // 处理 OpenAPI 3.0 requestBody
         if (operation.requestBody) {
             const requestBody = this.resolveReference(operation.requestBody);
@@ -98,7 +96,7 @@ class SwaggerParser {
         // 获取请求体类型
         const bodyParam = allParameters.find((p) => p.in === 'body');
         const requestBodyType = bodyParam?.schema
-            ? (0, utils_1.swaggerTypeToTsType)(bodyParam.schema)
+            ? (0, utils_1.swaggerTypeToTsType)(bodyParam.schema, this.getAllSchemas())
             : undefined;
         // 解析参数信息
         const parameters = allParameters.map((param) => {
@@ -118,6 +116,7 @@ class SwaggerParser {
             path,
             description: operation.summary || operation.description,
             tags: operation.tags || [],
+            deprecated: operation.deprecated,
             parameters,
             responseType,
             requestBodyType
@@ -130,12 +129,12 @@ class SwaggerParser {
     parseTypes() {
         const types = [];
         // Debug log
-        console.log('解析类型定义...');
-        console.log('Has components:', !!this.document.components);
+        utils_1.logger.debug('解析类型定义...');
+        utils_1.logger.debugKV('components', !!this.document.components);
         if (this.document.components) {
-            console.log('Has schemas:', !!this.document.components.schemas);
+            utils_1.logger.debugKV('schemas', !!this.document.components.schemas);
             if (this.document.components.schemas) {
-                console.log('Schema keys:', Object.keys(this.document.components.schemas));
+                utils_1.logger.debugKV('schema 列表', Object.keys(this.document.components.schemas).join(', '));
             }
         }
         // 解析 OpenAPI 3.x components.schemas
@@ -170,7 +169,7 @@ class SwaggerParser {
                 const comment = value.description
                     ? ` /** ${value.description} */`
                     : '';
-                return `${comment}\n  ${key}${optional}: ${type};`;
+                return `${comment}\n  ${(0, utils_1.formatTsPropertyName)(key)}${optional}: ${type};`;
             })
                 .join('\n');
             definition = `export interface ${typeName} {\n${properties}\n}`;
@@ -186,7 +185,7 @@ class SwaggerParser {
             const enumValues = schema.enum
                 .map((value, index) => {
                 const key = this.getEnumMemberName(schema, value, index);
-                return `  ${key} = '${value}'`;
+                return `  ${key} = ${JSON.stringify(String(value))}`;
             })
                 .join(',\n');
             definition = `export enum ${typeName} {\n${enumValues}\n}`;
@@ -225,19 +224,45 @@ class SwaggerParser {
      * @param value 可能带有 $ref 的对象
      * @returns 引用解析后的对象
      */
-    resolveReference(value) {
+    resolveReference(value, seenRefs = new Set(), depth = 0) {
         if (!value || !value.$ref) {
             return value;
         }
-        const refPath = value.$ref.replace(/^#\//, '').split('/');
+        const ref = value.$ref;
+        if (!ref.startsWith('#/')) {
+            throw new Error(`暂不支持外部 $ref 引用: ${ref}`);
+        }
+        if (depth >= MAX_REF_RESOLVE_DEPTH) {
+            throw new Error(`$ref 解析超过最大深度: ${ref}`);
+        }
+        if (seenRefs.has(ref)) {
+            throw new Error(`检测到循环 $ref 引用: ${ref}`);
+        }
+        seenRefs.add(ref);
+        const refPath = ref
+            .replace(/^#\//, '')
+            .split('/')
+            .map((segment) => decodeURIComponent(segment).replace(/~1/g, '/').replace(/~0/g, '~'));
         let current = this.document;
         for (const segment of refPath) {
             current = current?.[segment];
-            if (!current) {
-                return value;
+            if (current === undefined) {
+                throw new Error(`无法解析 $ref 引用: ${ref}`);
             }
         }
-        return current;
+        return this.resolveReference(current, seenRefs, depth + 1);
+    }
+    /**
+     * 合并同名同位置参数，后出现的 operation 级参数覆盖 path 级参数
+     * @param parameters 参数数组
+     * @returns 合并后的参数数组
+     */
+    mergeParameters(parameters) {
+        const merged = new Map();
+        for (const parameter of parameters) {
+            merged.set(`${parameter.in}:${parameter.name}`, parameter);
+        }
+        return Array.from(merged.values());
     }
     /**
      * 按标签分组API
@@ -248,7 +273,9 @@ class SwaggerParser {
         const groupedApis = new Map();
         for (const api of apis) {
             const tags = api.tags.length > 0 ? api.tags : ['default'];
-            for (const tag of tags) {
+            const strategy = this.config.multiTagStrategy ?? 'first';
+            const groupTags = strategy === 'all' ? [tags.join('-')] : [tags[0]];
+            for (const tag of groupTags) {
                 if (!groupedApis.has(tag)) {
                     groupedApis.set(tag, []);
                 }

package/dist/index.js

@@ -62,32 +62,36 @@ class Swagger2API {
      */
     async generate() {
         try {
-            console.log('🚀 开始生成API接口文件...');
+            utils_1.logger.banner('🚀 swagger2api-v3', '开始生成 API 接口文件');
+            utils_1.logger.setTotalSteps(4);
             // 1. 加载Swagger文档
-            console.log('📖 加载Swagger文档...');
+            utils_1.logger.stepTitle('📖', '加载 Swagger 文档');
             const document = await (0, utils_1.loadSwaggerDocument)(this.config.input);
-            console.log(`✅ 成功加载文档: ${document.info.title} v${document.info.version}`);
+            utils_1.logger.success(`文档加载成功: ${document.info.title} v${document.info.version}`);
             // 2. 解析文档
-            console.log('🔍 解析API接口...');
+            utils_1.logger.stepTitle('🔍', '解析 API 接口');
             const parser = new parser_1.SwaggerParser(document, this.config);
             const apis = this.filterApis(parser.parseApis());
             const types = parser.parseTypes();
             const groupedApis = parser.groupApisByTags(apis);
-            console.log(`✅ 解析完成: ${apis.length} 个接口, ${types.length} 个类型`);
+            utils_1.logger.success(`解析完成: ${apis.length} 个接口, ${types.length} 个类型`);
             if (this.config.groupByTags) {
-                console.log(`📁 按标签分组: ${groupedApis.size} 个分组`);
+                utils_1.logger.info(`按标签分组: ${groupedApis.size} 个分组`);
                 for (const [tag, tagApis] of groupedApis) {
-                    console.log(`   - ${tag}: ${tagApis.length} 个接口`);
+                    utils_1.logger.listItem(tag, `${tagApis.length} 个接口`);
                 }
             }
             // 3. 生成代码
-            console.log('⚡ 生成代码文件...');
+            utils_1.logger.stepTitle('⚡', '生成代码文件');
             const generator = new generator_1.CodeGenerator(this.config);
             await generator.generateAll(apis, types, groupedApis);
-            console.log(`✅ 代码生成完成，输出目录: ${this.config.output}`);
+            // 4. 完成
+            utils_1.logger.stepTitle('📦', '生成完成');
+            utils_1.logger.path('输出目录', this.config.output);
+            utils_1.logger.done('API 接口文件生成完成');
         }
         catch (error) {
-            console.error('❌ 生成失败:', error);
+            utils_1.logger.error('生成失败', error);
             throw error;
         }
     }
@@ -97,8 +101,7 @@ class Swagger2API {
     validateConfig() {
         const errors = (0, validator_1.validateSwaggerConfig)(this.config);
         if (errors.length > 0) {
-            console.error('❌ 配置验证失败:');
-            errors.forEach((error) => console.error(`   - ${error}`));
+            utils_1.logger.errorList('配置验证失败:', errors);
             return false;
         }
         return true;
@@ -134,9 +137,9 @@ async function generateFromConfig(configPath) {
         let config;
         // 读取并解析 JSON 配置文件
         if (!fs.existsSync(fullPath)) {
-            console.error(`❌ 找不到配置文件: ${fullPath}`);
-            console.error('请确保配置文件存在并且路径正确');
-            console.error('提示: 运行 swagger2api-v3 init 来创建配置文件');
+            utils_1.logger.error(`找不到配置文件: ${fullPath}`);
+            utils_1.logger.error('请确保配置文件存在并且路径正确');
+            utils_1.logger.error('提示: 运行 swagger2api-v3 init 来创建配置文件');
             process.exit(1);
         }
         const configContent = fs.readFileSync(fullPath, 'utf-8');
@@ -149,12 +152,12 @@ async function generateFromConfig(configPath) {
     }
     catch (error) {
         if (error instanceof SyntaxError) {
-            console.error(`❌ 配置文件 JSON 格式错误: ${fullPath}`);
-            console.error('请检查 JSON 语法是否正确');
-            console.error('错误详情:', error.message);
+            utils_1.logger.error(`配置文件 JSON 格式错误: ${fullPath}`);
+            utils_1.logger.error('请检查 JSON 语法是否正确');
+            utils_1.logger.error(`错误详情: ${error.message}`);
         }
         else {
-            console.error('❌ 加载配置文件失败:', error);
+            utils_1.logger.error('加载配置文件失败', error);
         }
         process.exit(1);
     }

package/dist/types/index.d.ts

@@ -15,6 +15,8 @@ export interface SwaggerConfig {
     generator: 'typescript' | 'javascript';
     /** 按 tags 分组生成文件 */
     groupByTags: boolean;
+    /** 多 tag 接口分组策略，first 只使用第一个 tag，all 将所有 tags 合成一个分组 */
+    multiTagStrategy?: 'first' | 'all';
     /** 是否覆盖更新，默认为true。为true时会先删除输出目录下的所有文件 */
     overwrite?: boolean;
     /** 接口路径公共前缀，默认为空字符串 */
@@ -373,6 +375,8 @@ export interface ApiInfo {
     description?: string;
     /** 标签 */
     tags: string[];
+    /** 是否废弃 */
+    deprecated?: boolean;
     /** 参数 */
     parameters: ParameterInfo[];
     /** 响应类型 */

package/dist/utils/file.js

@@ -43,6 +43,7 @@ exports.writeFile = writeFile;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const axios_1 = __importDefault(require("axios"));
+const logger_1 = require("./logger");
 /**
  * 确保目录存在，如果不存在则创建
  * @param dirPath 目录路径
@@ -70,12 +71,12 @@ async function loadSwaggerDocument(input) {
     try {
         if (input.startsWith('http://') || input.startsWith('https://')) {
             const { data } = await axios_1.default.get(input);
-            console.log('Loaded from URL:', input);
+            logger_1.logger.debug(`从 URL 加载: ${input}`);
             if (data.components?.schemas) {
-                console.log('Schemas count:', Object.keys(data.components.schemas).length);
+                logger_1.logger.debugKV('schemas 数量', Object.keys(data.components.schemas).length);
             }
             else {
-                console.log('No schemas in loaded data');
+                logger_1.logger.debug('加载的数据中未发现 schemas');
             }
             return data;
         }

package/dist/utils/index.d.ts

@@ -2,3 +2,4 @@ export * from './naming';
 export * from './type';
 export * from './file';
 export * from './comment';
+export * from './logger';

package/dist/utils/index.js

@@ -18,3 +18,4 @@ __exportStar(require("./naming"), exports);
 __exportStar(require("./type"), exports);
 __exportStar(require("./file"), exports);
 __exportStar(require("./comment"), exports);
+__exportStar(require("./logger"), exports);

package/dist/utils/logger.d.ts

@@ -0,0 +1,115 @@
+/**
+ * 轻量级终端日志工具（零依赖，基于 ANSI 转义码）
+ */
+/**
+ * 日志工具类
+ *
+ * 提供统一的、带颜色的终端输出格式。
+ * error 方法不使用颜色码，确保 console.error 的参数为纯文本，
+ * 兼容测试中对 console.error 的 spy 断言。
+ */
+declare class Logger {
+    private step;
+    private totalSteps;
+    /**
+     * 写入标准输出
+     * @param message 输出内容
+     */
+    private log;
+    /**
+     * 写入错误输出
+     * @param message 输出内容
+     */
+    private fail;
+    /**
+     * 格式化未知错误
+     * @param error 错误对象
+     * @returns 错误文案
+     */
+    private formatError;
+    /**
+     * 输出带图标的状态行
+     * @param symbol 状态图标
+     * @param message 消息内容
+     */
+    private status;
+    /**
+     * 设置总步骤数
+     * @param n 步骤总数
+     */
+    setTotalSteps(n: number): void;
+    /**
+     * 输出步骤标题
+     * @param emoji 步骤图标
+     * @param title 步骤标题
+     */
+    stepTitle(emoji: string, title: string): void;
+    /**
+     * 输出成功信息
+     * @param message 消息内容
+     */
+    success(message: string): void;
+    /**
+     * 输出信息
+     * @param message 消息内容
+     */
+    info(message: string): void;
+    /**
+     * 输出文件/路径信息
+     * @param label 标签
+     * @param path 路径
+     */
+    path(label: string, path: string): void;
+    /**
+     * 输出警告信息
+     * @param message 消息内容
+     */
+    warn(message: string): void;
+    /**
+     * 输出错误信息（不使用颜色码，兼容测试断言）
+     * @param message 消息内容
+     * @param error 错误对象
+     */
+    error(message: string, error?: unknown): void;
+    /**
+     * 输出错误列表
+     * @param title 错误标题
+     * @param items 错误项列表
+     */
+    errorList(title: string, items: string[]): void;
+    /**
+     * 输出调试信息（灰色暗淡）
+     * @param message 消息内容
+     */
+    debug(message: string): void;
+    /**
+     * 输出调试键值对
+     * @param key 键名
+     * @param value 键值
+     */
+    debugKV(key: string, value: string | number | boolean): void;
+    /**
+     * 输出列表项
+     * @param label 列表项标签
+     * @param detail 列表项详情
+     */
+    listItem(label: string, detail: string): void;
+    /**
+     * 输出分隔线
+     */
+    divider(): void;
+    /**
+     * 输出横幅标题
+     * @param title 标题
+     * @param subtitle 副标题（可选）
+     */
+    banner(title: string, subtitle?: string): void;
+    /**
+     * 输出完成横幅
+     * @param message 完成消息
+     */
+    done(message: string): void;
+}
+/** 日志单例 */
+export declare const logger: Logger;
+export {};

package/dist/utils/logger.js

@@ -0,0 +1,261 @@
+"use strict";
+/**
+ * 轻量级终端日志工具（零依赖，基于 ANSI 转义码）
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = void 0;
+/** 终端是否支持颜色输出 */
+const supportsColor = process.stdout.isTTY &&
+    process.env.NODE_ENV !== 'test' &&
+    process.env.NO_COLOR === undefined;
+/** 日志左侧缩进 */
+const INDENT = '  ';
+/** 列表标签默认宽度 */
+const LIST_LABEL_WIDTH = 22;
+/** 日志图标 */
+const icon = {
+    success: '✅',
+    info: 'ℹ',
+    warn: '⚠',
+    error: '❌',
+    debug: '·',
+    path: '📂',
+    bullet: '•'
+};
+/**
+ * 包裹 ANSI 颜色码
+ * @param code ANSI 转义码
+ * @param text 文本内容
+ * @returns 带颜色的字符串（不支持颜色时返回原文）
+ */
+function wrap(code, text) {
+    return supportsColor ? `\x1b[${code}m${text}\x1b[0m` : text;
+}
+/** 颜色与样式快捷方法 */
+const style = {
+    /**
+     * 加粗文本
+     * @param text 文本内容
+     * @returns 格式化后的文本
+     */
+    bold(text) {
+        return wrap('1', text);
+    },
+    /**
+     * 弱化文本
+     * @param text 文本内容
+     * @returns 格式化后的文本
+     */
+    dim(text) {
+        return wrap('2', text);
+    },
+    /**
+     * 绿色文本
+     * @param text 文本内容
+     * @returns 格式化后的文本
+     */
+    green(text) {
+        return wrap('32', text);
+    },
+    /**
+     * 黄色文本
+     * @param text 文本内容
+     * @returns 格式化后的文本
+     */
+    yellow(text) {
+        return wrap('33', text);
+    },
+    /**
+     * 紫色文本
+     * @param text 文本内容
+     * @returns 格式化后的文本
+     */
+    magenta(text) {
+        return wrap('35', text);
+    },
+    /**
+     * 青色文本
+     * @param text 文本内容
+     * @returns 格式化后的文本
+     */
+    cyan(text) {
+        return wrap('36', text);
+    },
+    /**
+     * 灰色文本
+     * @param text 文本内容
+     * @returns 格式化后的文本
+     */
+    gray(text) {
+        return wrap('90', text);
+    }
+};
+/**
+ * 日志工具类
+ *
+ * 提供统一的、带颜色的终端输出格式。
+ * error 方法不使用颜色码，确保 console.error 的参数为纯文本，
+ * 兼容测试中对 console.error 的 spy 断言。
+ */
+class Logger {
+    constructor() {
+        this.step = 0;
+        this.totalSteps = 0;
+    }
+    /**
+     * 写入标准输出
+     * @param message 输出内容
+     */
+    log(message = '') {
+        console.log(message);
+    }
+    /**
+     * 写入错误输出
+     * @param message 输出内容
+     */
+    fail(message) {
+        console.error(message);
+    }
+    /**
+     * 格式化未知错误
+     * @param error 错误对象
+     * @returns 错误文案
+     */
+    formatError(error) {
+        if (error instanceof Error) {
+            return error.message ? `${error.name}: ${error.message}` : error.name;
+        }
+        return String(error);
+    }
+    /**
+     * 输出带图标的状态行
+     * @param symbol 状态图标
+     * @param message 消息内容
+     */
+    status(symbol, message) {
+        this.log(`${INDENT}${symbol}  ${message}`);
+    }
+    /**
+     * 设置总步骤数
+     * @param n 步骤总数
+     */
+    setTotalSteps(n) {
+        this.totalSteps = n;
+        this.step = 0;
+    }
+    /**
+     * 输出步骤标题
+     * @param emoji 步骤图标
+     * @param title 步骤标题
+     */
+    stepTitle(emoji, title) {
+        this.step++;
+        const progress = this.totalSteps > 0
+            ? style.dim(`[${this.step}/${this.totalSteps}] `)
+            : '';
+        this.log();
+        this.log(`${INDENT}${progress}${emoji}  ${style.bold(title)}`);
+    }
+    /**
+     * 输出成功信息
+     * @param message 消息内容
+     */
+    success(message) {
+        this.status(style.green(icon.success), message);
+    }
+    /**
+     * 输出信息
+     * @param message 消息内容
+     */
+    info(message) {
+        this.status(style.cyan(icon.info), message);
+    }
+    /**
+     * 输出文件/路径信息
+     * @param label 标签
+     * @param path 路径
+     */
+    path(label, path) {
+        this.status(icon.path, `${style.dim(label)}: ${style.bold(path)}`);
+    }
+    /**
+     * 输出警告信息
+     * @param message 消息内容
+     */
+    warn(message) {
+        this.status(style.yellow(icon.warn), message);
+    }
+    /**
+     * 输出错误信息（不使用颜色码，兼容测试断言）
+     * @param message 消息内容
+     * @param error 错误对象
+     */
+    error(message, error) {
+        const detail = error === undefined ? message : `${message}: ${this.formatError(error)}`;
+        this.fail(`${icon.error} ${detail}`);
+    }
+    /**
+     * 输出错误列表
+     * @param title 错误标题
+     * @param items 错误项列表
+     */
+    errorList(title, items) {
+        this.fail(`${icon.error} ${title}`);
+        items.forEach((item) => this.fail(`${INDENT} - ${item}`));
+    }
+    /**
+     * 输出调试信息（灰色暗淡）
+     * @param message 消息内容
+     */
+    debug(message) {
+        this.status(style.gray(icon.debug), style.gray(message));
+    }
+    /**
+     * 输出调试键值对
+     * @param key 键名
+     * @param value 键值
+     */
+    debugKV(key, value) {
+        this.status(style.gray(icon.debug), `${style.gray(key)}: ${style.gray(String(value))}`);
+    }
+    /**
+     * 输出列表项
+     * @param label 列表项标签
+     * @param detail 列表项详情
+     */
+    listItem(label, detail) {
+        const paddedLabel = label.padEnd(LIST_LABEL_WIDTH, ' ');
+        this.log(`${INDENT}   ${style.dim(icon.bullet)} ${style.cyan(paddedLabel)} ${style.dim(detail)}`);
+    }
+    /**
+     * 输出分隔线
+     */
+    divider() {
+        const line = '─'.repeat(48);
+        this.log(`${INDENT}${style.dim(line)}`);
+    }
+    /**
+     * 输出横幅标题
+     * @param title 标题
+     * @param subtitle 副标题（可选）
+     */
+    banner(title, subtitle) {
+        this.log();
+        this.log(`${INDENT}${style.bold(style.magenta(title))}`);
+        if (subtitle) {
+            this.log(`${INDENT}${style.dim(subtitle)}`);
+        }
+        this.log();
+    }
+    /**
+     * 输出完成横幅
+     * @param message 完成消息
+     */
+    done(message) {
+        this.log();
+        this.log(`${INDENT}${style.green(icon.success)}  ${style.bold(message)}`);
+        this.log();
+    }
+}
+/** 日志单例 */
+exports.logger = new Logger();

package/dist/utils/type.d.ts

@@ -1,4 +1,16 @@
 import { SwaggerParameter, SwaggerSchema, SwaggerResponses } from '../types';
+/**
+ * 判断字符串是否为合法 TypeScript 标识符
+ * @param name 属性名
+ * @returns 是否为合法标识符
+ */
+export declare function isValidIdentifier(name: string): boolean;
+/**
+ * 格式化 TypeScript 属性名
+ * @param name 属性名
+ * @returns 可用于类型声明的属性名
+ */
+export declare function formatTsPropertyName(name: string): string;
 /**
  * 移除联合类型中的顶层 null 类型
  * @param typeStr 类型字符串

package/dist/utils/type.js

@@ -1,5 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidIdentifier = isValidIdentifier;
+exports.formatTsPropertyName = formatTsPropertyName;
 exports.stripNullFromUnion = stripNullFromUnion;
 exports.swaggerTypeToTsType = swaggerTypeToTsType;
 exports.getRefName = getRefName;
@@ -7,6 +9,22 @@ exports.swaggerParameterToSchema = swaggerParameterToSchema;
 exports.getResponseType = getResponseType;
 exports.getSchemaFromContent = getSchemaFromContent;
 const naming_1 = require("./naming");
+/**
+ * 判断字符串是否为合法 TypeScript 标识符
+ * @param name 属性名
+ * @returns 是否为合法标识符
+ */
+function isValidIdentifier(name) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name);
+}
+/**
+ * 格式化 TypeScript 属性名
+ * @param name 属性名
+ * @returns 可用于类型声明的属性名
+ */
+function formatTsPropertyName(name) {
+    return isValidIdentifier(name) ? name : JSON.stringify(name);
+}
 /**
  * 移除联合类型中的顶层 null 类型
  * @param typeStr 类型字符串
@@ -78,7 +96,7 @@ function swaggerTypeToTsType(schema, schemas) {
     else if (schema.allOf) {
         const refSchema = schema.allOf.find((item) => item.$ref);
         const secondSchema = schema.allOf.find((item) => !item.$ref);
-        if (refSchema && secondSchema) {
+        if (refSchema && secondSchema && schema.allOf.length === 2) {
             const refName = getRefName(refSchema.$ref || '');
             const sanitizedRefName = (0, naming_1.sanitizeTypeName)(refName || '');
             if (secondSchema.properties) {
@@ -97,7 +115,7 @@ function swaggerTypeToTsType(schema, schemas) {
                         let type = swaggerTypeToTsType(value, schemas);
                         if (optional === '?')
                             type = stripNullFromUnion(type);
-                        return `${key}${optional}: ${type}`;
+                        return `${formatTsPropertyName(key)}${optional}: ${type}`;
                     })
                         .join('; ')} }`;
                     baseType = `${sanitizedRefName}<${combinedType}>`;
@@ -112,9 +130,10 @@ function swaggerTypeToTsType(schema, schemas) {
         }
         else {
             const types = schema.allOf
-                .map((item) => swaggerTypeToTsType(item))
+                .map((item) => swaggerTypeToTsType(item, schemas))
                 .filter((type) => type !== 'any');
-            baseType = types.length > 0 ? types[0] : 'any';
+            const uniqueTypes = Array.from(new Set(types));
+            baseType = uniqueTypes.length > 0 ? uniqueTypes.join(' & ') : 'any';
         }
     }
     else if (schema.anyOf || schema.oneOf) {
@@ -162,7 +181,7 @@ function swaggerTypeToTsType(schema, schemas) {
                 let type = swaggerTypeToTsType(value, schemas);
                 if (optional === '?')
                     type = stripNullFromUnion(type);
-                return `  ${key}${optional}: ${type};`;
+                return `  ${formatTsPropertyName(key)}${optional}: ${type};`;
             })
                 .join('\n');
             baseType = `{\n${properties}\n}`;
@@ -228,7 +247,7 @@ function toLiteralType(value) {
     if (value === null)
         return 'null';
     if (typeof value === 'string')
-        return `'${value}'`;
+        return JSON.stringify(value);
     return String(value);
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swagger2api-v3",
-  "version": "1.1.9",
+  "version": "1.1.10",
   "description": "A command-line tool for generating TypeScript API interfaces from OpenAPI 3.x / Swagger 3.0 documentation",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -18,20 +18,21 @@
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",
     "test:ci": "jest --ci --coverage --watchAll=false",
-    "build": "tsc && npm run copy:schema",
+    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0",
+    "build": "tsc && pnpm run copy:schema",
     "copy:schema": "node build/copy-schema.js",
     "clean": "rimraf dist",
-    "prebuild": "npm run clean",
+    "prebuild": "pnpm run clean",
     "start": "node dist/cli/index.js",
-    "dev": "npm run build && npm start",
+    "dev": "pnpm run build && pnpm start",
     "lint": "prettier --write .",
-    "generate": "npm run build && node dist/cli/index.js generate",
-    "init": "npm run build && node dist/cli/index.js init",
-    "validate": "npm run build && node dist/cli/index.js validate",
-    "swagger:generate": "npm run generate",
-    "swagger:run": "npm run generate",
-    "swagger:init": "npm run init",
-    "swagger:validate": "npm run validate"
+    "generate": "pnpm run build && node dist/cli/index.js generate",
+    "init": "pnpm run build && node dist/cli/index.js init",
+    "validate": "pnpm run build && node dist/cli/index.js validate",
+    "swagger:generate": "pnpm run generate",
+    "swagger:run": "pnpm run generate",
+    "swagger:init": "pnpm run init",
+    "swagger:validate": "pnpm run validate"
   },
   "keywords": [
     "swagger",
@@ -55,15 +56,16 @@
   "packageManager": "pnpm@10.11.0",
   "devDependencies": {
     "@types/jest": "^30.0.0",
-    "@types/node": "^24.3.1",
+    "@types/node": "^24.13.2",
+    "conventional-changelog-cli": "^5.0.0",
     "jest": "^30.4.2",
-    "prettier": "^3.6.2",
-    "rimraf": "^6.0.1",
+    "prettier": "^3.8.4",
+    "rimraf": "^6.1.3",
     "ts-jest": "^29.4.11",
-    "typescript": "^5.9.2"
+    "typescript": "^6.0.3"
   },
   "dependencies": {
-    "axios": "^1.11.0",
-    "commander": "^12.0.0"
+    "axios": "^1.18.1",
+    "commander": "^12.1.0"
   }
 }