swagger2api-v3 1.1.6 → 1.1.8

package/dist/core/generator.js

@@ -95,13 +95,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 +117,7 @@ class CodeGenerator {
             return `${comment}${definition}`;
         })
             .join('\n\n');
-        return `${header}${typeDefinitions}\n`;
+        return `${header}\n\n${typeDefinitions}\n`;
     }
     /**
      * 按标签生成API文件
@@ -158,11 +157,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 +233,7 @@ class CodeGenerator {
     }
     /**
      * 生成直接参数形式
-     * @param parameters Swagger参数数组
+     * @param parameters OpenAPI 参数数组
      * @returns 函数参数字符串
      */
     generateDirectParameters(parameters, isJavaScript = false) {
@@ -241,7 +241,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 +273,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 +283,6 @@ class CodeGenerator {
      * @returns 类型字符串
      */
     getTypeFromSchema(schema) {
-        if (schema.$ref) {
-            return schema.$ref.split('/').pop() || 'any';
-        }
         return (0, utils_1.swaggerTypeToTsType)(schema);
     }
     /**
@@ -395,7 +376,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 +411,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}'`);
@@ -467,15 +444,7 @@ class CodeGenerator {
             // 导出单个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 +467,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命令
      */

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,12 @@ export declare class SwaggerParser {
      * @returns 类型信息
      */
     private parseTypeDefinition;
+    /**
+     * 解析本地 $ref 引用对象
+     * @param value 可能带有 $ref 的对象
+     * @returns 引用解析后的对象
+     */
+    private resolveReference;
     /**
      * 按标签分组API
      * @param apis API接口数组
@@ -53,6 +59,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

@@ -11,14 +11,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接口
@@ -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,7 +94,7 @@ 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
@@ -107,16 +102,14 @@ class SwaggerParser {
             : 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
@@ -232,6 +216,25 @@ class SwaggerParser {
             description: schema.description
         };
     }
+    /**
+     * 解析本地 $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接口数组
@@ -285,12 +288,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;
 /**

package/dist/types/index.d.ts

@@ -5,6 +5,8 @@
  * Swagger配置接口
  */
 export interface SwaggerConfig {
+    /** 本地 JSON Schema 路径，用于编辑器提示 */
+    $schema?: string;
     /** Swagger JSON 文件路径或 URL */
     input: string;
     /** 输出目录 */
@@ -33,65 +35,96 @@ export interface SwaggerConfig {
     methodNameIgnorePrefix?: string[];
     /** 是否在生成的方法名中添加 HTTP method 后缀，默认为 true。true: userListPost, false: userList */
     addMethodSuffix?: boolean;
+    /** 接口过滤配置 */
+    filter?: FilterConfig;
+    /** 自定义生成文件头部注释 */
+    headerComment?: string;
+}
+/**
+ * 接口过滤配置
+ */
+export interface FilterConfig {
+    /** 包含规则 */
+    include?: TagFilterConfig;
+    /** 排除规则 */
+    exclude?: TagFilterConfig;
+}
+/**
+ * 标签过滤配置
+ */
+export interface TagFilterConfig {
+    /** 需要匹配的标签名称 */
+    tags?: string[];
 }
 /**
  * 标签分组配置
  */
 export interface TagGroupingConfig {
     /** 启用标签分组 */
-    enabled: boolean;
+    enabled?: boolean;
     /** 为每个标签创建子目录 */
-    createSubDirectories: boolean;
+    createSubDirectories?: boolean;
     /** 文件命名方式 */
-    fileNaming: 'tag' | 'kebab-case' | 'camelCase';
+    fileNaming?: 'tag' | 'kebab-case' | 'camelCase';
 }
 /**
  * 生成选项
  */
 export interface GenerationOptions {
     /** 是否生成数据模型 */
-    generateModels: boolean;
+    generateModels?: boolean;
     /** 是否生成 API 接口 */
-    generateApis: boolean;
+    generateApis?: boolean;
     /** 是否生成入口文件 */
-    generateIndex: boolean;
+    generateIndex?: boolean;
     /** 是否使用 Axios */
-    useAxios: boolean;
+    useAxios?: boolean;
     /** 是否添加详细注释 */
-    addComments: boolean;
+    addComments?: boolean;
     /** 是否格式化代码 */
-    prettify: boolean;
+    prettify?: boolean;
 }
 /**
  * 注释配置
  */
 export interface CommentConfig {
     /** 包含接口描述 */
-    includeDescription: boolean;
+    includeDescription?: boolean;
     /** 包含参数信息 */
-    includeParameters: boolean;
+    includeParameters?: boolean;
     /** 包含返回值信息 */
-    includeResponses: boolean;
+    includeResponses?: boolean;
     /** 包含示例 */
-    includeExamples: boolean;
+    includeExamples?: boolean;
 }
 /**
- * Swagger文档结构
+ * OpenAPI 文档结构
  */
 export interface SwaggerDocument {
-    swagger?: string;
-    openapi?: string;
+    openapi: string;
     info: SwaggerInfo;
-    host?: string;
-    basePath?: string;
-    schemes?: string[];
-    consumes?: string[];
-    produces?: string[];
+    servers?: OpenAPIServer[];
     paths: SwaggerPaths;
-    definitions?: SwaggerDefinitions;
     components?: SwaggerComponents;
     tags?: SwaggerTag[];
 }
+/**
+ * OpenAPI Server 对象
+ */
+export interface OpenAPIServer {
+    /** Server URL */
+    url: string;
+    /** Server 描述 */
+    description?: string;
+    /** Server URL 变量 */
+    variables?: {
+        [name: string]: {
+            default: string;
+            enum?: string[];
+            description?: string;
+        };
+    };
+}
 /**
  * Swagger信息
  */
@@ -145,8 +178,6 @@ export interface SwaggerOperation {
     summary?: string;
     description?: string;
     operationId?: string;
-    consumes?: string[];
-    produces?: string[];
     parameters?: SwaggerParameter[];
     requestBody?: SwaggerRequestBody;
     responses: SwaggerResponses;
@@ -156,6 +187,8 @@ export interface SwaggerOperation {
  * Swagger请求体 (OpenAPI 3.0)
  */
 export interface SwaggerRequestBody {
+    /** 本地引用路径 */
+    $ref?: string;
     description?: string;
     content: {
         [mediaType: string]: {
@@ -169,11 +202,13 @@ export interface SwaggerRequestBody {
     required?: boolean;
 }
 /**
- * Swagger参数
+ * OpenAPI 参数
  */
 export interface SwaggerParameter {
+    /** 本地引用路径 */
+    $ref?: string;
     name: string;
-    in: 'query' | 'header' | 'path' | 'formData' | 'body';
+    in: 'query' | 'header' | 'path' | 'body' | 'cookie';
     description?: string;
     required?: boolean;
     type?: string;
@@ -184,17 +219,25 @@ export interface SwaggerParameter {
     default?: any;
 }
 /**
- * Swagger响应
+ * OpenAPI 响应
  */
 export interface SwaggerResponses {
     [statusCode: string]: SwaggerResponse;
 }
 /**
- * Swagger响应项
+ * OpenAPI 响应项
  */
 export interface SwaggerResponse {
     description: string;
-    schema?: SwaggerSchema;
+    content?: {
+        [mediaType: string]: {
+            schema?: SwaggerSchema;
+            example?: any;
+            examples?: {
+                [name: string]: any;
+            };
+        };
+    };
     headers?: {
         [name: string]: SwaggerHeader;
     };
@@ -214,10 +257,10 @@ export interface SwaggerHeader {
     default?: any;
 }
 /**
- * Swagger模式
+ * OpenAPI Schema
  */
 export interface SwaggerSchema {
-    type?: string;
+    type?: string | string[];
     format?: string;
     title?: string;
     description?: string;
@@ -255,12 +298,6 @@ export interface SwaggerItems {
     default?: any;
     $ref?: string;
 }
-/**
- * Swagger定义
- */
-export interface SwaggerDefinitions {
-    [name: string]: SwaggerSchema;
-}
 /**
  * Swagger组件 (OpenAPI 3.0)
  */
@@ -348,7 +385,7 @@ export interface ParameterInfo {
     /** 参数类型 */
     type: string;
     /** 参数位置 */
-    in: 'query' | 'header' | 'path' | 'formData' | 'body';
+    in: 'query' | 'header' | 'path' | 'body' | 'cookie';
     /** 是否必需 */
     required: boolean;
     /** 参数描述 */

package/dist/utils/comment.d.ts

@@ -0,0 +1,8 @@
+import { SwaggerParameter } from '../types';
+/**
+ * 生成接口注释
+ * @param operation Swagger操作对象
+ * @param parameters 参数列表
+ * @returns 注释字符串
+ */
+export declare function generateApiComment(operation: any, parameters: SwaggerParameter[]): string;