swagger2api-v3 1.1.10 → 1.1.11

package/dist/core/generator.js

@@ -39,13 +39,19 @@ const fs = __importStar(require("fs"));
 const child_process_1 = require("child_process");
 const util_1 = require("util");
 const utils_1 = require("../utils");
+const query_parameter_generator_1 = require("./query-parameter-generator");
 const execPromise = (0, util_1.promisify)(child_process_1.exec);
 /**
  * 代码生成器
  */
 class CodeGenerator {
+    /**
+     * 创建代码生成器
+     * @param config 生成配置
+     */
     constructor(config) {
         this.config = config;
+        this.outputRoot = path.resolve(config.output);
     }
     /**
      * 生成所有文件
@@ -54,17 +60,27 @@ class CodeGenerator {
      * @param groupedApis 按标签分组的API
      */
     async generateAll(apis, types, groupedApis) {
+        this.assertSafeOutputDirectory();
+        if (this.config.options?.generateApis !== false &&
+            this.config.groupByTags) {
+            this.validateTagFolders(groupedApis);
+        }
         // 根据overwrite配置决定是否清空目录
         if (this.config.overwrite !== false) {
             // 默认为true，清空输出目录
-            (0, utils_1.removeDirectory)(this.config.output);
+            (0, utils_1.removeDirectory)(this.outputRoot);
         }
         // 确保输出目录存在
-        (0, utils_1.ensureDirectoryExists)(this.config.output);
+        (0, utils_1.ensureDirectoryExists)(this.outputRoot);
         // 生成类型文件（仅在 TypeScript 模式下生成）
         if (this.config.generator === 'typescript' &&
             this.config.options?.generateModels !== false) {
-            await this.generateTypesFile(types);
+            const rootTypes = this.config.groupByTags
+                ? types
+                : this.config.options?.generateApis === false
+                    ? types
+                    : this.mergeTypeDefinitions(types, (0, query_parameter_generator_1.generateQueryParameterTypes)(apis, types.map((type) => type.name)));
+            await this.generateTypesFile(rootTypes);
         }
         // 生成API文件
         if (this.config.options?.generateApis !== false) {
@@ -90,7 +106,7 @@ class CodeGenerator {
      */
     async generateTypesFile(types) {
         const content = this.generateTypesContent(types);
-        const filePath = path.join(this.config.output, 'types.ts');
+        const filePath = this.resolveOutputPath('types.ts');
         this.writeGeneratedFile(filePath, content);
     }
     /**
@@ -105,23 +121,66 @@ class CodeGenerator {
             ' * 此文件由 swagger2api-v3 自动生成，请勿手动修改',
             ' */'
         ]);
-        const typeDefinitions = types
+        const typeDefinitions = this.renderTypeDefinitions(types);
+        return `${header}\n\n${typeDefinitions}\n`;
+    }
+    /**
+     * 渲染类型定义列表
+     * @param types 类型定义数组
+     * @returns 类型定义内容
+     */
+    renderTypeDefinitions(types) {
+        return types
             .map((type) => {
             const comment = type.description
                 ? `/**\n * ${type.description}\n */\n`
                 : '';
-            // 通用处理：检测通用响应容器类型并转换为泛型接口
-            let definition = type.definition;
-            if (this.isGenericResponseContainer(type, definition)) {
-                const typeName = type.name;
-                definition = definition
-                    .replace(`export interface ${typeName} {`, `export interface ${typeName}<T = Record<string, any>> {`)
-                    .replace('data: Record<string, any>;', 'data: T;');
-            }
-            return `${comment}${definition}`;
+            return `${comment}${type.definition}`;
         })
             .join('\n\n');
-        return `${header}\n\n${typeDefinitions}\n`;
+    }
+    /**
+     * 合并类型定义
+     * @param modelTypes 组件模型类型
+     * @param parameterTypes 查询参数类型
+     * @returns 合并后的类型定义
+     */
+    mergeTypeDefinitions(modelTypes, parameterTypes) {
+        return [...modelTypes, ...parameterTypes];
+    }
+    /**
+     * 判断是否应提取查询参数类型
+     * @returns 是否提取查询参数类型
+     */
+    shouldExtractQueryParameterTypes() {
+        return (this.config.generator === 'typescript' &&
+            this.config.options?.generateModels !== false);
+    }
+    /**
+     * 生成 tag 内的查询参数类型文件
+     * @param folderName tag 目录名
+     * @param apis 当前 tag 的 API 接口
+     * @param modelTypes 组件模型类型
+     */
+    generateTagParameterTypesFile(folderName, apis, modelTypes) {
+        const parameterTypes = (0, query_parameter_generator_1.generateQueryParameterTypes)(apis, modelTypes.map((type) => type.name));
+        if (parameterTypes.length === 0)
+            return;
+        const usedModelTypes = (0, query_parameter_generator_1.collectQueryParameterModelTypes)(apis, modelTypes);
+        const content = [
+            this.generateHeader([
+                '/**',
+                ' * API 查询参数类型',
+                ' * 此文件由 swagger2api-v3 自动生成，请勿手动修改',
+                ' */'
+            ])
+        ];
+        if (usedModelTypes.length > 0) {
+            content.push(`import type { ${usedModelTypes.join(', ')} } from '../../types';`);
+        }
+        content.push('', this.renderTypeDefinitions(parameterTypes), '');
+        const filePath = this.resolveOutputPath(folderName, 'types', 'index.ts');
+        this.writeGeneratedFile(filePath, content.join('\n'));
     }
     /**
      * 按标签生成API文件
@@ -131,9 +190,12 @@ class CodeGenerator {
     async generateApiFilesByTags(groupedApis, types) {
         for (const [tag, apis] of groupedApis) {
             const folderName = this.getTagFileName(tag);
-            const tagFolderPath = path.join(this.config.output, folderName);
+            const tagFolderPath = this.resolveOutputPath(folderName);
             // 确保tag文件夹存在
             (0, utils_1.ensureDirectoryExists)(tagFolderPath);
+            if (this.shouldExtractQueryParameterTypes()) {
+                this.generateTagParameterTypesFile(folderName, apis, types);
+            }
             const ext = this.config.generator === 'javascript' ? 'js' : 'ts';
             const filePath = path.join(tagFolderPath, `index.${ext}`);
             const content = this.generateApiFileContent(apis, types, tag);
@@ -147,7 +209,7 @@ class CodeGenerator {
      */
     async generateSingleApiFile(apis, types) {
         const ext = this.config.generator === 'javascript' ? 'js' : 'ts';
-        const filePath = path.join(this.config.output, `api.${ext}`);
+        const filePath = this.resolveOutputPath(`api.${ext}`);
         const content = this.generateApiFileContent(apis, types);
         this.writeGeneratedFile(filePath, content);
     }
@@ -169,33 +231,50 @@ class CodeGenerator {
             ]),
             importTemplate + ';'
         ];
+        const extractQueryParameterTypes = this.shouldExtractQueryParameterTypes();
+        const queryParameterTypes = extractQueryParameterTypes
+            ? (0, query_parameter_generator_1.generateQueryParameterTypes)(apis, types.map((type) => type.name))
+            : [];
+        const queryParameterTypeNames = queryParameterTypes.map((type) => type.name);
         // 收集当前文件实际使用的类型
-        const usedTypes = this.collectUsedTypes(apis, types); // 传入 types
+        const usedTypes = this.collectUsedTypes(apis, types, extractQueryParameterTypes);
+        const queryParameterTypeByApi = new Map(queryParameterTypes.map((type) => [type.api, type.name]));
         // 添加类型导入（仅在 TypeScript 且生成类型文件时）
         if (this.config.generator === 'typescript' &&
             this.config.options?.generateModels !== false &&
-            usedTypes.length > 0) {
-            const typeNames = usedTypes.join(', ');
+            (usedTypes.length > 0 || (!tag && queryParameterTypeNames.length > 0))) {
+            const typeNames = Array.from(new Set([...usedTypes, ...(tag ? [] : queryParameterTypeNames)]))
+                .sort()
+                .join(', ');
             const typesPath = tag ? '../types' : './types';
             header.push(`import type { ${typeNames} } from '${typesPath}';`);
         }
+        if (tag && queryParameterTypeNames.length > 0) {
+            const typeNames = queryParameterTypeNames.sort().join(', ');
+            header.push(`import type { ${typeNames} } from './types';`);
+        }
         header.push('');
         const apiImplementations = apis
-            .map((api) => this.generateApiFunction(api))
+            .map((api) => this.generateApiFunction(api, extractQueryParameterTypes
+            ? queryParameterTypeByApi.get(api)
+            : undefined))
             .join('\n\n');
         return `${header.join('\n')}${apiImplementations}\n`;
     }
     /**
      * 生成单个API函数
      * @param api API接口信息
+     * @param queryParameterTypeName 查询参数类型名
      * @returns API函数代码
      */
-    generateApiFunction(api) {
+    generateApiFunction(api, queryParameterTypeName) {
         const parts = [];
         // 生成注释
         if (this.config.options?.addComments !== false) {
+            const pathParameterNames = this.createPathParameterNames(api.parameters.filter((parameter) => parameter.in === 'path'));
+            let pathParameterIndex = 0;
             const swaggerParams = api.parameters.map((p) => ({
-                name: p.name,
+                name: p.in === 'path' ? pathParameterNames[pathParameterIndex++] : p.name,
                 in: p.in,
                 required: p.required,
                 type: p.type,
@@ -213,7 +292,7 @@ class CodeGenerator {
             schema: p.schema || { type: p.type }
         }));
         // 生成直接参数形式
-        const functionParams = this.generateDirectParameters(swaggerParameters, this.config.generator === 'javascript');
+        const functionParams = this.generateDirectParameters(swaggerParameters, this.config.generator === 'javascript', queryParameterTypeName);
         const responseType = this.config.options?.generateModels === false
             ? 'any'
             : api.responseType || 'any';
@@ -240,31 +319,41 @@ class CodeGenerator {
     /**
      * 生成直接参数形式
      * @param parameters OpenAPI 参数数组
+     * @param isJavaScript 是否生成 JavaScript 参数
+     * @param queryParameterTypeName 查询参数类型名
      * @returns 函数参数字符串
      */
-    generateDirectParameters(parameters, isJavaScript = false) {
+    generateDirectParameters(parameters, isJavaScript = false, queryParameterTypeName) {
         const params = [];
         const queryParams = parameters.filter((p) => p.in === 'query');
         const pathParams = parameters.filter((p) => p.in === 'path');
         const bodyParams = parameters.filter((p) => p.in === 'body');
-        // 合并路径参数和查询参数为一个params对象
-        const allParams = [...pathParams, ...queryParams];
-        if (allParams.length > 0) {
+        const bodyParam = bodyParams[0];
+        const hasRequiredBody = bodyParam?.required === true;
+        const pathParameterNames = this.createPathParameterNames(pathParams);
+        pathParams.forEach((parameter, index) => {
+            const parameterName = pathParameterNames[index];
+            if (isJavaScript) {
+                params.push(parameterName);
+            }
+            else {
+                params.push(`${parameterName}: ${this.getSafeGeneratedType(parameter.type)}`);
+            }
+        });
+        if (queryParams.length > 0) {
             if (isJavaScript) {
                 params.push('params');
             }
             else {
-                const paramType = allParams
-                    .map((p) => {
-                    const optional = p.required ? '' : '?';
-                    const type = this.getSafeGeneratedType(p.type);
-                    return `${(0, utils_1.formatTsPropertyName)(p.name)}${optional}: ${type}`;
-                })
-                    .join(', ');
-                // 检查是否所有参数都是可选的
-                const allOptional = allParams.every((p) => !p.required);
-                const optionalModifier = allOptional ? '?' : '';
-                params.push(`params${optionalModifier}: { ${paramType} }`);
+                const allOptional = queryParams.every((p) => !p.required);
+                const optionalModifier = allOptional && !hasRequiredBody ? '?' : '';
+                if (queryParameterTypeName) {
+                    params.push(`params${optionalModifier}: ${queryParameterTypeName}`);
+                }
+                else {
+                    const paramType = this.renderInlineQueryParameterMembers(queryParams);
+                    params.push(`params${optionalModifier}: { ${paramType} }`);
+                }
             }
         }
         // 请求体参数
@@ -273,28 +362,15 @@ class CodeGenerator {
                 params.push('data');
             }
             else {
-                const bodyParam = bodyParams[0];
-                const bodyType = bodyParam.schema
-                    ? this.getTypeFromSchema(bodyParam.schema)
-                    : bodyParam.type;
-                params.push(`data: ${this.getSafeGeneratedType(bodyType)}`);
+                const bodyType = bodyParam.type;
+                const optionalModifier = bodyParam.required ? '' : '?';
+                params.push(`data${optionalModifier}: ${this.getSafeGeneratedType(bodyType)}`);
             }
         }
         // 添加可选的config参数
         params.push(isJavaScript ? 'config' : 'config?: any');
         return params.join(', ');
     }
-    /**
-     * 从schema获取类型
-     * @param schema Swagger schema
-     * @returns 类型字符串
-     */
-    getTypeFromSchema(schema) {
-        if (this.config.options?.generateModels === false) {
-            return 'any';
-        }
-        return (0, utils_1.swaggerTypeToTsType)(schema);
-    }
     /**
      * 获取当前配置下可安全输出的类型
      * @param type 类型字符串
@@ -307,13 +383,30 @@ class CodeGenerator {
             return type;
         return this.isPrimitiveType(type) ? type : 'any';
     }
+    /**
+     * 渲染内联查询参数类型成员
+     * @param parameters 查询参数数组
+     * @returns 内联类型成员
+     */
+    renderInlineQueryParameterMembers(parameters) {
+        return parameters
+            .map((parameter) => {
+            const optional = parameter.required ? '' : '?';
+            let type = this.getSafeGeneratedType(parameter.type);
+            if (optional)
+                type = (0, utils_1.stripNullFromUnion)(type);
+            return `${(0, utils_1.formatTsPropertyName)(parameter.name)}${optional}: ${type}`;
+        })
+            .join(', ');
+    }
     /**
      * 收集API数组中实际使用的类型
      * @param apis API接口数组
      * @param definedTypes 已定义的类型数组
+     * @param excludeQueryParameters 是否排除查询参数
      * @returns 使用的类型名称数组
      */
-    collectUsedTypes(apis, definedTypes) {
+    collectUsedTypes(apis, definedTypes, excludeQueryParameters = false) {
         const usedTypes = new Set();
         apis.forEach((api) => {
             // 收集响应类型
@@ -325,17 +418,15 @@ class CodeGenerator {
             }
             // 收集参数类型
             api.parameters.forEach((param) => {
-                if (param.schema) {
-                    const type = this.getTypeFromSchema(param.schema);
-                    if (type && type !== 'any' && !this.isPrimitiveType(type)) {
-                        this.extractTypeNames(type).forEach((typeName) => {
+                if (excludeQueryParameters && param.in === 'query')
+                    return;
+                if (param.type && param.type !== 'any') {
+                    if (!this.isPrimitiveType(param.type)) {
+                        this.extractTypeNames(param.type).forEach((typeName) => {
                             usedTypes.add(typeName);
                         });
                     }
                 }
-                else if (param.type && !this.isPrimitiveType(param.type)) {
-                    usedTypes.add(param.type);
-                }
             });
         });
         // 如果提供了 definedTypes，则只保留已定义的类型
@@ -378,29 +469,13 @@ class CodeGenerator {
             'object',
             'array',
             'any',
+            'blob',
             'void',
             'null',
             'undefined'
         ];
         return primitiveTypes.includes(type.toLowerCase());
     }
-    /**
-     * 检测是否为通用响应容器类型
-     * @param type 类型信息
-     * @param definition 类型定义
-     * @returns 是否为通用响应容器类型
-     */
-    isGenericResponseContainer(type, definition) {
-        // 检查是否为接口定义
-        if (!definition.includes(`export interface ${type.name} {`)) {
-            return false;
-        }
-        // 检查是否包含 data 字段且类型为 Record<string, any>
-        const hasDataField = definition.includes('data: Record<string, any>;');
-        // 检查是否包含其他常见的响应容器字段
-        const hasCommonFields = ['code', 'message', 'success', 'status'].some((field) => new RegExp(`\\b${field}\\??:`).test(definition));
-        return hasDataField && hasCommonFields;
-    }
     /**
      * 生成请求配置
      * @param api API接口信息
@@ -416,26 +491,21 @@ class CodeGenerator {
         }
         const pathParams = api.parameters.filter((p) => p.in === 'path');
         const queryParams = api.parameters.filter((p) => p.in === 'query');
+        const pathParameterNames = this.createPathParameterNames(pathParams);
         if (pathParams.length > 0) {
-            // 替换路径参数，从params对象中获取
-            pathParams.forEach((param) => {
-                url = url.replace(`{${param.name}}`, `\${params.${param.name}}`);
+            url = this.escapeTemplateLiteral(url);
+            pathParams.forEach((param, index) => {
+                const placeholder = this.escapeTemplateLiteral(`{${param.name}}`);
+                const replacement = `\${${pathParameterNames[index]}}`;
+                url = url.split(placeholder).join(replacement);
             });
             config.push(`url: \`${url}\``);
         }
         else {
-            config.push(`url: '${url}'`);
+            config.push(`url: ${this.toSingleQuotedString(url)}`);
         }
-        // 查询参数和路径参数都从params对象中获取
         if (queryParams.length > 0) {
-            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');
-            }
+            config.push('params');
         }
         // 请求体数据
         const bodyParams = api.parameters.filter((p) => p.in === 'body');
@@ -451,14 +521,26 @@ class CodeGenerator {
         return `{\n    ${config.join(',\n    ')}\n  }`;
     }
     /**
-     * 生成 params 对象字段访问表达式
-     * @param name 参数名
-     * @returns 字段访问表达式
+     * 创建不重复的路径参数变量名
+     * @param parameters OpenAPI 路径参数
+     * @returns 路径参数变量名
      */
-    getParamAccessExpression(name) {
-        return (0, utils_1.isValidIdentifier)(name)
-            ? `params.${name}`
-            : `params[${JSON.stringify(name)}]`;
+    createPathParameterNames(parameters) {
+        const usedNames = new Set(['params', 'data', 'config']);
+        return parameters.map((parameter, index) => {
+            const normalizedName = parameter.name.replace(/[^A-Za-z0-9_$]/g, '_');
+            const baseName = (0, utils_1.isValidIdentifier)(normalizedName)
+                ? normalizedName
+                : `pathParam${index + 1}`;
+            let parameterName = baseName;
+            let suffix = 2;
+            while (usedNames.has(parameterName)) {
+                parameterName = `${baseName}_${suffix}`;
+                suffix++;
+            }
+            usedNames.add(parameterName);
+            return parameterName;
+        });
     }
     /**
      * 生成入口文件
@@ -476,7 +558,7 @@ class CodeGenerator {
                 // 按标签导出
                 for (const tag of groupedApis.keys()) {
                     const folderName = this.getTagFileName(tag);
-                    exports.push(`export * from './${folderName}';`);
+                    exports.push(`export * from ${this.toSingleQuotedString(`./${folderName}`)};`);
                 }
             }
             else {
@@ -486,9 +568,31 @@ 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}`);
+        const filePath = this.resolveOutputPath(`index.${ext}`);
         this.writeGeneratedFile(filePath, content);
     }
+    /**
+     * 校验输出目录不会覆盖当前工作目录或其父目录
+     */
+    assertSafeOutputDirectory() {
+        const currentDirectory = path.resolve(process.cwd());
+        if (this.outputRoot === currentDirectory ||
+            (0, utils_1.isPathInside)(this.outputRoot, currentDirectory)) {
+            throw new Error('输出目录不能是当前工作目录或其父目录');
+        }
+    }
+    /**
+     * 解析并校验输出目录内的文件路径
+     * @param segments 输出目录下的路径片段
+     * @returns 安全的绝对路径
+     */
+    resolveOutputPath(...segments) {
+        const targetPath = path.resolve(this.outputRoot, ...segments);
+        if (!(0, utils_1.isPathInside)(this.outputRoot, targetPath)) {
+            throw new Error(`生成路径超出输出目录: ${targetPath}`);
+        }
+        return targetPath;
+    }
     /**
      * 写入生成文件，overwrite=false 时保留已存在文件
      * @param filePath 文件路径
@@ -507,17 +611,68 @@ class CodeGenerator {
      */
     getTagFileName(tag) {
         const cleanTag = (0, utils_1.sanitizeFilename)(tag);
+        let folderName;
         switch (this.config.tagGrouping?.fileNaming) {
             case 'camelCase':
-                return (0, utils_1.toCamelCase)(cleanTag);
+                folderName = (0, utils_1.toCamelCase)(cleanTag);
+                break;
             case 'kebab-case':
-                return (0, utils_1.toKebabCase)(cleanTag);
+                folderName = (0, utils_1.toKebabCase)(cleanTag);
+                break;
             case 'tag':
-                return cleanTag.toLowerCase();
+                folderName = cleanTag.toLowerCase();
+                break;
             default:
-                return (0, utils_1.toCamelCase)(cleanTag);
+                folderName = (0, utils_1.toCamelCase)(cleanTag);
+                break;
+        }
+        if (!folderName || folderName === '.' || folderName === '..') {
+            throw new Error(`无效的标签名称: ${JSON.stringify(tag)}`);
+        }
+        return folderName;
+    }
+    /**
+     * 校验所有标签生成的目录名称安全且不重复
+     * @param groupedApis 按标签分组的 API
+     */
+    validateTagFolders(groupedApis) {
+        const folderOwners = new Map();
+        for (const tag of groupedApis.keys()) {
+            const folderName = this.getTagFileName(tag);
+            const normalizedFolderName = folderName.toLowerCase();
+            const existingTag = folderOwners.get(normalizedFolderName);
+            if (existingTag !== undefined && existingTag !== tag) {
+                throw new Error(`标签目录名称冲突: ${existingTag} 和 ${tag} 都会生成 ${folderName}`);
+            }
+            folderOwners.set(normalizedFolderName, tag);
         }
     }
+    /**
+     * 转义模板字符串中的特殊字符
+     * @param value 原始字符串
+     * @returns 可安全写入模板字符串的内容
+     */
+    escapeTemplateLiteral(value) {
+        return value
+            .replace(/\\/g, '\\\\')
+            .replace(/`/g, '\\`')
+            .replace(/\$\{/g, '\\${');
+    }
+    /**
+     * 将字符串转换为安全的单引号字面量
+     * @param value 原始字符串
+     * @returns 单引号字符串字面量
+     */
+    toSingleQuotedString(value) {
+        const escapedValue = value
+            .replace(/\\/g, '\\\\')
+            .replace(/'/g, "\\'")
+            .replace(/\r/g, '\\r')
+            .replace(/\n/g, '\\n')
+            .replace(/\u2028/g, '\\u2028')
+            .replace(/\u2029/g, '\\u2029');
+        return `'${escapedValue}'`;
+    }
     /**
      * 生成文件头部注释
      * @param defaultHeader 默认头部注释

package/dist/core/parser.d.ts

@@ -1,10 +1,15 @@
 import { SwaggerDocument, ApiInfo, TypeInfo, SwaggerConfig } from '../types';
 /**
- * Swagger文档解析器
+ * OpenAPI 3.0 文档解析器
  */
 export declare class SwaggerParser {
     private document;
     private config;
+    /**
+     * 创建 OpenAPI 文档解析器
+     * @param document OpenAPI 文档
+     * @param config 生成配置
+     */
     constructor(document: SwaggerDocument, config: SwaggerConfig);
     /**
      * 获取 OpenAPI components.schemas
@@ -30,27 +35,20 @@ export declare class SwaggerParser {
      * @returns 类型信息数组
      */
     parseTypes(): TypeInfo[];
-    /**
-     * 解析单个类型定义
-     * @param name 类型名称
-     * @param schema 模式对象
-     * @returns 类型信息
-     */
-    private parseTypeDefinition;
-    /**
-     * 获取枚举成员名称
-     * @param schema 枚举 schema
-     * @param value 枚举值
-     * @param index 枚举值索引
-     * @returns 枚举成员名称
-     */
-    private getEnumMemberName;
     /**
      * 解析本地 $ref 引用对象
      * @param value 可能带有 $ref 的对象
+     * @param seenRefs 已访问的引用
+     * @param depth 当前解析深度
      * @returns 引用解析后的对象
      */
     private resolveReference;
+    /**
+     * 解析响应对象中的本地引用
+     * @param responses OpenAPI 响应集合
+     * @returns 已解析的响应集合
+     */
+    private resolveResponses;
     /**
      * 合并同名同位置参数，后出现的 operation 级参数覆盖 path 级参数
      * @param parameters 参数数组