swagger2api-v3 1.1.8 → 1.1.10

package/dist/index.js

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

package/dist/types/index.d.ts

@@ -15,6 +15,8 @@ export interface SwaggerConfig {
     generator: 'typescript' | 'javascript';
     /** 按 tags 分组生成文件 */
     groupByTags: boolean;
+    /** 多 tag 接口分组策略，first 只使用第一个 tag，all 将所有 tags 合成一个分组 */
+    multiTagStrategy?: 'first' | 'all';
     /** 是否覆盖更新，默认为true。为true时会先删除输出目录下的所有文件 */
     overwrite?: boolean;
     /** 接口路径公共前缀，默认为空字符串 */
@@ -286,6 +288,10 @@ export interface SwaggerSchema {
     externalDocs?: SwaggerExternalDocs;
     nullable?: boolean;
     deprecated?: boolean;
+    /** OpenAPI 扩展字段：枚举变量名 */
+    'x-enum-varnames'?: string[];
+    /** OpenAPI 扩展字段：枚举名称 */
+    'x-enumNames'?: string[];
 }
 /**
  * Swagger项目
@@ -369,6 +375,8 @@ export interface ApiInfo {
     description?: string;
     /** 标签 */
     tags: string[];
+    /** 是否废弃 */
+    deprecated?: boolean;
     /** 参数 */
     parameters: ParameterInfo[];
     /** 响应类型 */

package/dist/utils/comment.d.ts

@@ -1,8 +1,23 @@
-import { SwaggerParameter } from '../types';
+import { ParameterInfo } from '../types';
+/**
+ * 注释生成需要的操作信息
+ */
+export interface ApiCommentOperation {
+    /** 接口摘要 */
+    summary?: string;
+    /** 接口描述 */
+    description?: string;
+    /** 是否废弃 */
+    deprecated?: boolean;
+}
+/**
+ * 注释生成需要的参数信息
+ */
+export type ApiCommentParameter = Pick<ParameterInfo, 'in' | 'description'>;
 /**
  * 生成接口注释
- * @param operation Swagger操作对象
+ * @param operation 接口操作信息
  * @param parameters 参数列表
  * @returns 注释字符串
  */
-export declare function generateApiComment(operation: any, parameters: SwaggerParameter[]): string;
+export declare function generateApiComment(operation: ApiCommentOperation, parameters: ApiCommentParameter[]): string;

package/dist/utils/comment.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateApiComment = generateApiComment;
 /**
  * 生成接口注释
- * @param operation Swagger操作对象
+ * @param operation 接口操作信息
  * @param parameters 参数列表
  * @returns 注释字符串
  */

package/dist/utils/file.js

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

package/dist/utils/index.d.ts

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

package/dist/utils/index.js

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

package/dist/utils/logger.d.ts

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

package/dist/utils/logger.js

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

package/dist/utils/type.d.ts

@@ -1,4 +1,16 @@
-import { SwaggerParameter } from '../types';
+import { SwaggerParameter, SwaggerSchema, SwaggerResponses } from '../types';
+/**
+ * 判断字符串是否为合法 TypeScript 标识符
+ * @param name 属性名
+ * @returns 是否为合法标识符
+ */
+export declare function isValidIdentifier(name: string): boolean;
+/**
+ * 格式化 TypeScript 属性名
+ * @param name 属性名
+ * @returns 可用于类型声明的属性名
+ */
+export declare function formatTsPropertyName(name: string): string;
 /**
  * 移除联合类型中的顶层 null 类型
  * @param typeStr 类型字符串
@@ -11,29 +23,31 @@ export declare function stripNullFromUnion(typeStr: string): string;
  * @param schemas 可选的 schemas 上下文，用于查找被引用的类型定义
  * @returns TypeScript类型字符串
  */
-export declare function swaggerTypeToTsType(schema: any, schemas?: any): string;
+export declare function swaggerTypeToTsType(schema: SwaggerSchema | undefined | null, schemas?: Record<string, SwaggerSchema>): string;
+/**
+ * 从 $ref 字符串中提取引用名称
+ * @param ref OpenAPI $ref 字符串
+ * @returns 引用名称
+ */
+export declare function getRefName(ref: string): string;
 /**
  * 将 OpenAPI 参数转换为 schema 对象
  * @param parameter OpenAPI 参数
  * @returns 参数对应的 schema
  */
-export declare function swaggerParameterToSchema(parameter: SwaggerParameter): any;
-/**
- * 从 OpenAPI 参数生成 TypeScript 参数类型
- * @param parameters OpenAPI 参数数组
- * @returns TypeScript参数类型定义
- */
-export declare function generateParameterTypes(parameters: SwaggerParameter[]): string;
+export declare function swaggerParameterToSchema(parameter: SwaggerParameter): SwaggerSchema;
 /**
  * 获取响应类型
  * @param responses OpenAPI 响应对象
  * @param schemas OpenAPI components.schemas
  * @returns TypeScript类型字符串
  */
-export declare function getResponseType(responses: any, schemas?: any): string;
+export declare function getResponseType(responses: SwaggerResponses, schemas?: Record<string, SwaggerSchema>): string;
 /**
  * 从 OpenAPI content 对象中获取最合适的 schema
  * @param content OpenAPI content 对象
  * @returns 匹配到的 schema
  */
-export declare function getSchemaFromContent(content: any): any;
+export declare function getSchemaFromContent(content: Record<string, {
+    schema?: SwaggerSchema;
+}> | undefined): SwaggerSchema | undefined;