swagger2api-v3 1.1.8 → 1.1.10

package/README.md

@@ -2,12 +2,12 @@
 
 English | [中文](./README_CN.md)
 
-A powerful command-line tool for automatically generating TypeScript or JavaScript interface code from OpenAPI 3.0 documentation.
+A powerful command-line tool for automatically generating TypeScript or JavaScript interface code from OpenAPI 3.x / Swagger 3.0 documentation.
 
 ## ✨ Features
 
-- 🚀 **Fast Generation** - Quickly generate TypeScript interface code from Swagger JSON
-- 📁 **Smart Grouping** - Support automatic file grouping by Swagger tags
+- 🚀 **Fast Generation** - Quickly generate TypeScript interface code from OpenAPI/Swagger 3.0 JSON
+- 📁 **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
 - ⚙️ **Environment Adaptation** - Automatically detect project environment and generate corresponding configuration files
@@ -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                | -              | Swagger JSON file path or URL                                                                                                                                      |
+| `input`                  | string                | -              | OpenAPI/Swagger 3.0 JSON file path or URL                                                                                                                          |
 | `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,7 +35,11 @@ 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");
+const execPromise = (0, util_1.promisify)(child_process_1.exec);
 /**
  * 代码生成器
  */
@@ -87,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);
     }
     /**
      * 生成类型文件内容
@@ -133,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);
         }
     }
     /**
@@ -145,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文件内容
@@ -197,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);
         }
         // 生成函数签名
@@ -210,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}) => {`);
         // 生成请求配置
@@ -251,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(', ');
                 // 检查是否所有参数都是可选的
@@ -270,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参数
@@ -283,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接口数组
@@ -406,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');
@@ -422,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
@@ -433,20 +471,33 @@ class CodeGenerator {
             this.config.options?.generateModels !== false) {
             exports.push("export * from './types';");
         }
-        if (this.config.groupByTags) {
-            // 按标签导出
-            for (const tag of groupedApis.keys()) {
-                const folderName = this.getTagFileName(tag);
-                exports.push(`export * from './${folderName}';`);
+        if (this.config.options?.generateApis !== false) {
+            if (this.config.groupByTags) {
+                // 按标签导出
+                for (const tag of groupedApis.keys()) {
+                    const folderName = this.getTagFileName(tag);
+                    exports.push(`export * from './${folderName}';`);
+                }
+            }
+            else {
+                // 导出单个API文件
+                exports.push("export * from './api';");
             }
-        }
-        else {
-            // 导出单个API文件
-            exports.push("export * from './api';");
         }
         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);
     }
     /**
@@ -487,18 +538,15 @@ class CodeGenerator {
         if (!this.config.lint)
             return;
         try {
-            const { exec } = require('child_process');
-            const util = require('util');
-            const execPromise = util.promisify(exec);
-            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

@@ -37,12 +37,26 @@ export declare class SwaggerParser {
      * @returns 类型信息
      */
     private parseTypeDefinition;
+    /**
+     * 获取枚举成员名称
+     * @param schema 枚举 schema
+     * @param value 枚举值
+     * @param index 枚举值索引
+     * @returns 枚举成员名称
+     */
+    private getEnumMemberName;
     /**
      * 解析本地 $ref 引用对象
      * @param value 可能带有 $ref 的对象
      * @returns 引用解析后的对象
      */
     private resolveReference;
+    /**
+     * 合并同名同位置参数，后出现的 operation 级参数覆盖 path 级参数
+     * @param parameters 参数数组
+     * @returns 合并后的参数数组
+     */
+    private mergeParameters;
     /**
      * 按标签分组API
      * @param apis API接口数组

package/dist/core/parser.js

@@ -2,6 +2,16 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SwaggerParser = void 0;
 const utils_1 = require("../utils");
+const HTTP_METHODS = [
+    'get',
+    'post',
+    'put',
+    'delete',
+    'patch',
+    'head',
+    'options'
+];
+const MAX_REF_RESOLVE_DEPTH = 20;
 /**
  * Swagger文档解析器
  */
@@ -25,16 +35,7 @@ class SwaggerParser {
         const apis = [];
         const paths = this.document.paths;
         for (const [path, pathItem] of Object.entries(paths)) {
-            const methods = [
-                'get',
-                'post',
-                'put',
-                'delete',
-                'patch',
-                'head',
-                'options'
-            ];
-            for (const method of methods) {
+            for (const method of HTTP_METHODS) {
                 const operation = pathItem[method];
                 if (!operation)
                     continue;
@@ -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);
@@ -97,8 +95,8 @@ class SwaggerParser {
         const responseType = (0, utils_1.getResponseType)(operation.responses, this.getAllSchemas());
         // 获取请求体类型
         const bodyParam = allParameters.find((p) => p.in === 'body');
-        const requestBodyType = bodyParam
-            ? (0, utils_1.swaggerTypeToTsType)(bodyParam.schema)
+        const requestBodyType = 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}`;
@@ -178,29 +177,15 @@ class SwaggerParser {
         else if (schema.type === 'array') {
             // 数组类型 - 生成指向 items 类型的别名(不带 [])
             // 在引用时会自动添加 []
-            const itemType = (0, utils_1.swaggerTypeToTsType)(schema.items, allSchemas);
+            const itemType = (0, utils_1.swaggerTypeToTsType)(schema.items || {}, allSchemas);
             definition = `export type ${typeName} = ${itemType};`;
         }
         else if (schema.enum) {
             // 枚举类型
             const enumValues = schema.enum
                 .map((value, index) => {
-                let key = value;
-                // 优先使用 x-enum-varnames 或 x-enumNames 扩展字段
-                if ((schema['x-enum-varnames'] && schema['x-enum-varnames'][index]) ||
-                    (schema['x-enumNames'] && schema['x-enumNames'][index])) {
-                    key =
-                        schema['x-enum-varnames']?.[index] ||
-                            schema['x-enumNames']?.[index];
-                }
-                else if (/^\d+$/.test(value)) {
-                    // 对于数字枚举，使用 VALUE_ 前缀
-                    key = `VALUE_${value}`;
-                }
-                else {
-                    key = value.toUpperCase();
-                }
-                return `  ${key} = '${value}'`;
+                const key = this.getEnumMemberName(schema, value, index);
+                return `  ${key} = ${JSON.stringify(String(value))}`;
             })
                 .join(',\n');
             definition = `export enum ${typeName} {\n${enumValues}\n}`;
@@ -216,24 +201,68 @@ class SwaggerParser {
             description: schema.description
         };
     }
+    /**
+     * 获取枚举成员名称
+     * @param schema 枚举 schema
+     * @param value 枚举值
+     * @param index 枚举值索引
+     * @returns 枚举成员名称
+     */
+    getEnumMemberName(schema, value, index) {
+        const extensionName = schema['x-enum-varnames']?.[index] || schema['x-enumNames']?.[index];
+        if (extensionName) {
+            return extensionName;
+        }
+        const strValue = String(value);
+        if (/^\d+$/.test(strValue)) {
+            return `VALUE_${strValue}`;
+        }
+        return strValue.toUpperCase();
+    }
     /**
      * 解析本地 $ref 引用对象
      * @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
@@ -244,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, []);
                 }
@@ -265,16 +296,7 @@ class SwaggerParser {
         }
         // 从路径操作中获取
         for (const pathItem of Object.values(this.document.paths)) {
-            const methods = [
-                'get',
-                'post',
-                'put',
-                'delete',
-                'patch',
-                'head',
-                'options'
-            ];
-            for (const method of methods) {
+            for (const method of HTTP_METHODS) {
                 const operation = pathItem[method];
                 if (operation?.tags) {
                     operation.tags.forEach((tag) => tags.add(tag));