swagger2api-v3 1.1.7 → 1.1.9

package/dist/core/generator.js

@@ -35,7 +35,10 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CodeGenerator = void 0;
 const path = __importStar(require("path"));
+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);
 /**
  * 代码生成器
  */
@@ -95,13 +98,12 @@ class CodeGenerator {
      * @returns 类型文件内容
      */
     generateTypesContent(types) {
-        const header = [
+        const header = this.generateHeader([
             '/**',
             ' * API 类型定义',
             ' * 此文件由 swagger2api-v3 自动生成，请勿手动修改',
-            ' */',
-            ''
-        ].join('\n');
+            ' */'
+        ]);
         const typeDefinitions = types
             .map((type) => {
             const comment = type.description
@@ -118,7 +120,7 @@ class CodeGenerator {
             return `${comment}${definition}`;
         })
             .join('\n\n');
-        return `${header}${typeDefinitions}\n`;
+        return `${header}\n\n${typeDefinitions}\n`;
     }
     /**
      * 按标签生成API文件
@@ -158,11 +160,12 @@ class CodeGenerator {
     generateApiFileContent(apis, types, tag) {
         const importTemplate = this.config.importTemplate || "import { request } from '@/utils'";
         const header = [
-            '/**',
-            ` * ${tag ? `${tag} ` : ''}API 接口`,
-            ' * 此文件由 swagger2api-v3 自动生成，请勿手动修改',
-            ' */',
-            '',
+            this.generateHeader([
+                '/**',
+                ` * ${tag ? `${tag} ` : ''}API 接口`,
+                ' * 此文件由 swagger2api-v3 自动生成，请勿手动修改',
+                ' */'
+            ]),
             importTemplate + ';'
         ];
         // 收集当前文件实际使用的类型
@@ -233,7 +236,7 @@ class CodeGenerator {
     }
     /**
      * 生成直接参数形式
-     * @param parameters Swagger参数数组
+     * @param parameters OpenAPI 参数数组
      * @returns 函数参数字符串
      */
     generateDirectParameters(parameters, isJavaScript = false) {
@@ -241,7 +244,6 @@ class CodeGenerator {
         const queryParams = parameters.filter((p) => p.in === 'query');
         const pathParams = parameters.filter((p) => p.in === 'path');
         const bodyParams = parameters.filter((p) => p.in === 'body');
-        const formParams = parameters.filter((p) => p.in === 'formData');
         // 合并路径参数和查询参数为一个params对象
         const allParams = [...pathParams, ...queryParams];
         if (allParams.length > 0) {
@@ -274,21 +276,6 @@ class CodeGenerator {
                 params.push(`data: ${bodyType}`);
             }
         }
-        // 表单参数
-        if (formParams.length > 0) {
-            if (isJavaScript) {
-                params.push('data');
-            }
-            else {
-                const formType = formParams
-                    .map((p) => {
-                    const optional = p.required ? '' : '?';
-                    return `${p.name}${optional}: ${p.type}`;
-                })
-                    .join(', ');
-                params.push(`data: { ${formType} }`);
-            }
-        }
         // 添加可选的config参数
         params.push(isJavaScript ? 'config' : 'config?: any');
         return params.join(', ');
@@ -299,9 +286,6 @@ class CodeGenerator {
      * @returns 类型字符串
      */
     getTypeFromSchema(schema) {
-        if (schema.$ref) {
-            return schema.$ref.split('/').pop() || 'any';
-        }
         return (0, utils_1.swaggerTypeToTsType)(schema);
     }
     /**
@@ -395,7 +379,7 @@ class CodeGenerator {
         // 检查是否包含 data 字段且类型为 Record<string, any>
         const hasDataField = definition.includes('data: Record<string, any>;');
         // 检查是否包含其他常见的响应容器字段
-        const hasCommonFields = ['code', 'message', 'success', 'status'].some((field) => definition.includes(`${field}:`));
+        const hasCommonFields = ['code', 'message', 'success', 'status'].some((field) => new RegExp(`\\b${field}\\??:`).test(definition));
         return hasDataField && hasCommonFields;
     }
     /**
@@ -430,13 +414,9 @@ class CodeGenerator {
         }
         // 请求体数据
         const bodyParams = api.parameters.filter((p) => p.in === 'body');
-        const formParams = api.parameters.filter((p) => p.in === 'formData');
         if (bodyParams.length > 0) {
             config.push('data');
         }
-        else if (formParams.length > 0) {
-            config.push('data');
-        }
         // 在通用请求风格下添加 method 字段
         if (includeMethod) {
             config.push(`method: '${api.method}'`);
@@ -456,26 +436,20 @@ 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 = [
-            '/**',
-            ' * API 入口文件',
-            ' * 此文件由 swagger2api-v3 自动生成，请勿手动修改',
-            ' */',
-            '',
-            ...exports,
-            ''
-        ].join('\n');
+        const content = [this.generateHeader(), '', ...exports, ''].join('\n');
         const ext = this.config.generator === 'javascript' ? 'js' : 'ts';
         const filePath = path.join(this.config.output, `index.${ext}`);
         (0, utils_1.writeFile)(filePath, content);
@@ -498,6 +472,19 @@ class CodeGenerator {
                 return (0, utils_1.toCamelCase)(cleanTag);
         }
     }
+    /**
+     * 生成文件头部注释
+     * @param defaultHeader 默认头部注释
+     * @returns 文件头部注释内容
+     */
+    generateHeader(defaultHeader = [
+        '/**',
+        ' * API 入口文件',
+        ' * 此文件由 swagger2api-v3 自动生成，请勿手动修改',
+        ' */'
+    ]) {
+        return this.config.headerComment?.trim() || defaultHeader.join('\n');
+    }
     /**
      * 在所有文件生成完成后运行lint命令
      */
@@ -505,9 +492,6 @@ 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}`);
             const result = await execPromise(`${this.config.lint} ${this.config.output}`);
             if (result.stdout) {

package/dist/core/parser.d.ts

@@ -7,7 +7,7 @@ export declare class SwaggerParser {
     private config;
     constructor(document: SwaggerDocument, config: SwaggerConfig);
     /**
-     * 获取所有 schemas (包括 definitions 和 components.schemas)
+     * 获取 OpenAPI components.schemas
      * @returns schemas 对象
      */
     private getAllSchemas;
@@ -37,6 +37,20 @@ export declare class SwaggerParser {
      * @returns 类型信息
      */
     private parseTypeDefinition;
+    /**
+     * 获取枚举成员名称
+     * @param schema 枚举 schema
+     * @param value 枚举值
+     * @param index 枚举值索引
+     * @returns 枚举成员名称
+     */
+    private getEnumMemberName;
+    /**
+     * 解析本地 $ref 引用对象
+     * @param value 可能带有 $ref 的对象
+     * @returns 引用解析后的对象
+     */
+    private resolveReference;
     /**
      * 按标签分组API
      * @param apis API接口数组
@@ -53,6 +67,12 @@ export declare class SwaggerParser {
      * @returns 基础URL字符串
      */
     getBaseUrl(): string;
+    /**
+     * 解析 OpenAPI server 地址
+     * @param server OpenAPI server 对象
+     * @returns 替换默认变量后的 server URL
+     */
+    private resolveServerUrl;
     /**
      * 获取API文档信息
      * @returns API文档基本信息

package/dist/core/parser.js

@@ -2,6 +2,15 @@
 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'
+];
 /**
  * Swagger文档解析器
  */
@@ -11,14 +20,11 @@ class SwaggerParser {
         this.config = config;
     }
     /**
-     * 获取所有 schemas (包括 definitions 和 components.schemas)
+     * 获取 OpenAPI components.schemas
      * @returns schemas 对象
      */
     getAllSchemas() {
-        return {
-            ...(this.document.definitions || {}),
-            ...(this.document.components?.schemas || {})
-        };
+        return this.document.components?.schemas || {};
     }
     /**
      * 解析所有API接口
@@ -28,16 +34,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;
@@ -60,22 +57,20 @@ class SwaggerParser {
         const allParameters = [
             ...(globalParameters || []),
             ...(operation.parameters || [])
-        ];
+        ].map((parameter) => this.resolveReference(parameter));
         // 处理 OpenAPI 3.0 requestBody
         if (operation.requestBody) {
-            const requestBody = operation.requestBody;
-            if (requestBody.content && requestBody.content['application/json']) {
-                const schema = requestBody.content['application/json'].schema;
-                if (schema) {
-                    const bodyParam = {
-                        name: 'body',
-                        in: 'body',
-                        required: requestBody.required || false,
-                        schema: schema,
-                        type: 'object'
-                    };
-                    allParameters.push(bodyParam);
-                }
+            const requestBody = this.resolveReference(operation.requestBody);
+            const schema = (0, utils_1.getSchemaFromContent)(requestBody.content);
+            if (schema) {
+                const bodyParam = {
+                    name: 'body',
+                    in: 'body',
+                    required: requestBody.required || false,
+                    schema,
+                    type: 'object'
+                };
+                allParameters.push(bodyParam);
             }
         }
         // 生成函数名
@@ -99,24 +94,22 @@ class SwaggerParser {
         // 应用前缀忽略规则
         functionName = (0, utils_1.stripMethodNamePrefixes)(functionName, this.config.methodNameIgnorePrefix);
         // 获取响应类型
-        const responseType = (0, utils_1.getResponseType)(operation.responses);
+        const responseType = (0, utils_1.getResponseType)(operation.responses, this.getAllSchemas());
         // 获取请求体类型
         const bodyParam = allParameters.find((p) => p.in === 'body');
-        const requestBodyType = bodyParam
+        const requestBodyType = bodyParam?.schema
             ? (0, utils_1.swaggerTypeToTsType)(bodyParam.schema)
             : undefined;
         // 解析参数信息
         const parameters = allParameters.map((param) => {
-            const type = param.schema
-                ? (0, utils_1.swaggerTypeToTsType)(param.schema)
-                : (0, utils_1.swaggerTypeToTsType)({ type: param.type || 'string' });
+            const type = (0, utils_1.swaggerTypeToTsType)((0, utils_1.swaggerParameterToSchema)(param), this.getAllSchemas());
             return {
                 name: param.name,
                 type,
                 in: param.in,
                 required: param.required || false,
                 description: param.description,
-                schema: param.schema
+                schema: (0, utils_1.swaggerParameterToSchema)(param)
             };
         });
         return {
@@ -138,7 +131,6 @@ class SwaggerParser {
         const types = [];
         // Debug log
         console.log('解析类型定义...');
-        console.log('Has definitions:', !!this.document.definitions);
         console.log('Has components:', !!this.document.components);
         if (this.document.components) {
             console.log('Has schemas:', !!this.document.components.schemas);
@@ -146,15 +138,7 @@ class SwaggerParser {
                 console.log('Schema keys:', Object.keys(this.document.components.schemas));
             }
         }
-        // 解析 Swagger 2.0 definitions
-        if (this.document.definitions) {
-            for (const [name, schema] of Object.entries(this.document.definitions)) {
-                const sanitizedName = (0, utils_1.sanitizeTypeName)(name); // Use it
-                const typeInfo = this.parseTypeDefinition(sanitizedName, schema);
-                types.push(typeInfo);
-            }
-        }
-        // 解析 OpenAPI 3.0 components.schemas
+        // 解析 OpenAPI 3.x components.schemas
         if (this.document.components?.schemas) {
             for (const [name, schema] of Object.entries(this.document.components.schemas)) {
                 const sanitizedName = (0, utils_1.sanitizeTypeName)(name); // Use it
@@ -194,28 +178,14 @@ 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();
-                }
+                const key = this.getEnumMemberName(schema, value, index);
                 return `  ${key} = '${value}'`;
             })
                 .join(',\n');
@@ -232,6 +202,43 @@ 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) {
+        if (!value || !value.$ref) {
+            return value;
+        }
+        const refPath = value.$ref.replace(/^#\//, '').split('/');
+        let current = this.document;
+        for (const segment of refPath) {
+            current = current?.[segment];
+            if (!current) {
+                return value;
+            }
+        }
+        return current;
+    }
     /**
      * 按标签分组API
      * @param apis API接口数组
@@ -262,16 +269,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));
@@ -285,12 +283,23 @@ class SwaggerParser {
      * @returns 基础URL字符串
      */
     getBaseUrl() {
-        if (this.document.host) {
-            const scheme = this.document.schemes?.[0] || 'https';
-            const basePath = this.document.basePath || '';
-            return `${scheme}://${this.document.host}${basePath}`;
-        }
-        return '';
+        const server = this.document.servers?.[0];
+        if (!server)
+            return '';
+        return this.resolveServerUrl(server);
+    }
+    /**
+     * 解析 OpenAPI server 地址
+     * @param server OpenAPI server 对象
+     * @returns 替换默认变量后的 server URL
+     */
+    resolveServerUrl(server) {
+        if (!server.variables)
+            return server.url;
+        return server.url.replace(/\{([^}]+)\}/g, (match, name) => {
+            const variable = server.variables?.[name];
+            return variable?.default ?? match;
+        });
     }
     /**
      * 获取API文档信息

package/dist/index.d.ts

@@ -13,6 +13,12 @@ export declare class Swagger2API {
      * 验证配置
      */
     validateConfig(): boolean;
+    /**
+     * 根据配置过滤 API
+     * @param apis API接口数组
+     * @returns 过滤后的 API接口数组
+     */
+    private filterApis;
 }
 /**
  * 从配置文件生成API

package/dist/index.js

@@ -44,6 +44,7 @@ const fs = __importStar(require("fs"));
 const parser_1 = require("./core/parser");
 const generator_1 = require("./core/generator");
 const utils_1 = require("./utils");
+const validator_1 = require("./config/validator");
 /**
  * Swagger2API 主类
  */
@@ -69,7 +70,7 @@ class Swagger2API {
             // 2. 解析文档
             console.log('🔍 解析API接口...');
             const parser = new parser_1.SwaggerParser(document, this.config);
-            const apis = parser.parseApis();
+            const apis = this.filterApis(parser.parseApis());
             const types = parser.parseTypes();
             const groupedApis = parser.groupApisByTags(apis);
             console.log(`✅ 解析完成: ${apis.length} 个接口, ${types.length} 个类型`);
@@ -94,18 +95,7 @@ class Swagger2API {
      * 验证配置
      */
     validateConfig() {
-        const errors = [];
-        if (!this.config.input) {
-            errors.push('input 配置项不能为空');
-        }
-        if (!this.config.output) {
-            errors.push('output 配置项不能为空');
-        }
-        // 支持 typescript 与 javascript 两种生成器
-        if (this.config.generator !== 'typescript' &&
-            this.config.generator !== 'javascript') {
-            errors.push('目前只支持 typescript 或 javascript 生成器');
-        }
+        const errors = (0, validator_1.validateSwaggerConfig)(this.config);
         if (errors.length > 0) {
             console.error('❌ 配置验证失败:');
             errors.forEach((error) => console.error(`   - ${error}`));
@@ -113,6 +103,24 @@ class Swagger2API {
         }
         return true;
     }
+    /**
+     * 根据配置过滤 API
+     * @param apis API接口数组
+     * @returns 过滤后的 API接口数组
+     */
+    filterApis(apis) {
+        const includeTags = this.config.filter?.include?.tags;
+        const excludeTags = this.config.filter?.exclude?.tags;
+        if (!includeTags?.length && !excludeTags?.length) {
+            return apis;
+        }
+        return apis.filter((api) => {
+            const tags = api.tags || [];
+            const included = !includeTags?.length || tags.some((tag) => includeTags.includes(tag));
+            const excluded = !!excludeTags?.length && tags.some((tag) => excludeTags.includes(tag));
+            return included && !excluded;
+        });
+    }
 }
 exports.Swagger2API = Swagger2API;
 /**