swagger2api-v3 1.1.9 → 1.1.11

package/dist/index.d.ts

@@ -33,4 +33,5 @@ export declare function generate(config: SwaggerConfig): Promise<void>;
 export * from './types';
 export { SwaggerParser } from './core/parser';
 export { CodeGenerator } from './core/generator';
+export { OpenAPITypeGenerator } from './core/type-generator';
 export * from './utils';

package/dist/index.js

@@ -36,7 +36,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CodeGenerator = exports.SwaggerParser = exports.Swagger2API = void 0;
+exports.OpenAPITypeGenerator = exports.CodeGenerator = exports.SwaggerParser = exports.Swagger2API = void 0;
 exports.generateFromConfig = generateFromConfig;
 exports.generate = generate;
 const path = __importStar(require("path"));
@@ -62,32 +62,36 @@ class Swagger2API {
      */
     async generate() {
         try {
-            console.log('🚀 开始生成API接口文件...');
-            // 1. 加载Swagger文档
-            console.log('📖 加载Swagger文档...');
+            utils_1.logger.banner('🚀 swagger2api-v3', '开始生成 API 接口文件');
+            utils_1.logger.setTotalSteps(4);
+            // 1. 加载 OpenAPI 文档
+            utils_1.logger.stepTitle('📖', '加载 OpenAPI 文档');
             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);
     }
@@ -176,4 +179,6 @@ var parser_2 = require("./core/parser");
 Object.defineProperty(exports, "SwaggerParser", { enumerable: true, get: function () { return parser_2.SwaggerParser; } });
 var generator_2 = require("./core/generator");
 Object.defineProperty(exports, "CodeGenerator", { enumerable: true, get: function () { return generator_2.CodeGenerator; } });
+var type_generator_1 = require("./core/type-generator");
+Object.defineProperty(exports, "OpenAPITypeGenerator", { enumerable: true, get: function () { return type_generator_1.OpenAPITypeGenerator; } });
 __exportStar(require("./utils"), exports);

package/dist/types/index.d.ts

@@ -7,7 +7,7 @@
 export interface SwaggerConfig {
     /** 本地 JSON Schema 路径，用于编辑器提示 */
     $schema?: string;
-    /** Swagger JSON 文件路径或 URL */
+    /** OpenAPI 3.0 JSON/YAML 文件路径或 URL */
     input: string;
     /** 输出目录 */
     output: string;
@@ -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;
     /** 接口路径公共前缀，默认为空字符串 */
@@ -108,6 +110,13 @@ export interface SwaggerDocument {
     components?: SwaggerComponents;
     tags?: SwaggerTag[];
 }
+/**
+ * OpenAPI 引用对象
+ */
+export interface SwaggerReference {
+    /** 引用地址 */
+    $ref: string;
+}
 /**
  * OpenAPI Server 对象
  */
@@ -161,6 +170,8 @@ export interface SwaggerPaths {
  * Swagger路径项
  */
 export interface SwaggerPathItem {
+    /** Path Item 引用 */
+    $ref?: string;
     get?: SwaggerOperation;
     post?: SwaggerOperation;
     put?: SwaggerOperation;
@@ -168,6 +179,7 @@ export interface SwaggerPathItem {
     patch?: SwaggerOperation;
     head?: SwaggerOperation;
     options?: SwaggerOperation;
+    trace?: SwaggerOperation;
     parameters?: SwaggerParameter[];
 }
 /**
@@ -190,7 +202,7 @@ export interface SwaggerRequestBody {
     /** 本地引用路径 */
     $ref?: string;
     description?: string;
-    content: {
+    content?: {
         [mediaType: string]: {
             schema?: SwaggerSchema;
             example?: any;
@@ -222,13 +234,15 @@ export interface SwaggerParameter {
  * OpenAPI 响应
  */
 export interface SwaggerResponses {
-    [statusCode: string]: SwaggerResponse;
+    [statusCode: string]: SwaggerResponse | SwaggerReference;
 }
 /**
  * OpenAPI 响应项
  */
 export interface SwaggerResponse {
-    description: string;
+    /** 本地或已打包的引用路径 */
+    $ref?: string;
+    description?: string;
     content?: {
         [mediaType: string]: {
             schema?: SwaggerSchema;
@@ -279,7 +293,7 @@ export interface SwaggerSchema {
     $ref?: string;
     example?: any;
     examples?: any[];
-    discriminator?: string;
+    discriminator?: OpenAPIDiscriminator;
     readOnly?: boolean;
     writeOnly?: boolean;
     xml?: SwaggerXml;
@@ -291,6 +305,15 @@ export interface SwaggerSchema {
     /** OpenAPI 扩展字段：枚举名称 */
     'x-enumNames'?: string[];
 }
+/**
+ * OpenAPI discriminator 对象
+ */
+export interface OpenAPIDiscriminator {
+    /** 用作类型判别的属性名 */
+    propertyName: string;
+    /** 判别值到 Schema 引用的映射 */
+    mapping?: Record<string, string>;
+}
 /**
  * Swagger项目
  */
@@ -310,7 +333,7 @@ export interface SwaggerComponents {
         [name: string]: SwaggerSchema;
     };
     responses?: {
-        [name: string]: SwaggerResponse;
+        [name: string]: SwaggerResponse | SwaggerReference;
     };
     parameters?: {
         [name: string]: SwaggerParameter;
@@ -373,6 +396,8 @@ export interface ApiInfo {
     description?: string;
     /** 标签 */
     tags: string[];
+    /** 是否废弃 */
+    deprecated?: boolean;
     /** 参数 */
     parameters: ParameterInfo[];
     /** 响应类型 */

package/dist/utils/comment.d.ts

@@ -13,7 +13,10 @@ export interface ApiCommentOperation {
 /**
  * 注释生成需要的参数信息
  */
-export type ApiCommentParameter = Pick<ParameterInfo, 'in' | 'description'>;
+export type ApiCommentParameter = Pick<ParameterInfo, 'in' | 'description'> & {
+    /** 生成后的函数参数名 */
+    name?: string;
+};
 /**
  * 生成接口注释
  * @param operation 接口操作信息

package/dist/utils/comment.js

@@ -23,8 +23,12 @@ function generateApiComment(operation, parameters) {
         const hasData = bodyParams.length > 0;
         if (hasParams || hasData) {
             comments.push(' *');
-            if (hasParams) {
-                const paramDescriptions = [...pathParams, ...queryParams]
+            pathParams.forEach((param, index) => {
+                const name = param.name || `pathParam${index + 1}`;
+                comments.push(` * @param ${name} ${param.description || '路径参数'}`);
+            });
+            if (queryParams.length > 0) {
+                const paramDescriptions = queryParams
                     .map((param) => param.description || '')
                     .filter((description) => description)
                     .join(', ');

package/dist/utils/file.d.ts

@@ -10,9 +10,16 @@ export declare function ensureDirectoryExists(dirPath: string): void;
  */
 export declare function removeDirectory(dirPath: string): void;
 /**
- * 读取Swagger文档
- * @param input 文件路径或URL
- * @returns Swagger文档对象
+ * 判断目标路径是否严格位于父路径内部
+ * @param parentPath 父路径
+ * @param targetPath 目标路径
+ * @returns 目标路径是否位于父路径内部
+ */
+export declare function isPathInside(parentPath: string, targetPath: string): boolean;
+/**
+ * 读取并打包 OpenAPI 3.0 文档
+ * @param input 文件路径或 URL
+ * @returns OpenAPI 文档对象
  */
 export declare function loadSwaggerDocument(input: string): Promise<SwaggerDocument>;
 /**

package/dist/utils/file.js

@@ -32,17 +32,16 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ensureDirectoryExists = ensureDirectoryExists;
 exports.removeDirectory = removeDirectory;
+exports.isPathInside = isPathInside;
 exports.loadSwaggerDocument = loadSwaggerDocument;
 exports.writeFile = writeFile;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
-const axios_1 = __importDefault(require("axios"));
+const OpenAPIParser = require("@apidevtools/swagger-parser");
+const logger_1 = require("./logger");
 /**
  * 确保目录存在，如果不存在则创建
  * @param dirPath 目录路径
@@ -62,28 +61,59 @@ function removeDirectory(dirPath) {
     }
 }
 /**
- * 读取Swagger文档
- * @param input 文件路径或URL
- * @returns Swagger文档对象
+ * 判断目标路径是否严格位于父路径内部
+ * @param parentPath 父路径
+ * @param targetPath 目标路径
+ * @returns 目标路径是否位于父路径内部
+ */
+function isPathInside(parentPath, targetPath) {
+    const relativePath = path.relative(path.resolve(parentPath), path.resolve(targetPath));
+    return (relativePath !== '' &&
+        relativePath !== '..' &&
+        !relativePath.startsWith(`..${path.sep}`) &&
+        !path.isAbsolute(relativePath));
+}
+/**
+ * 读取并打包 OpenAPI 3.0 文档
+ * @param input 文件路径或 URL
+ * @returns OpenAPI 文档对象
  */
 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);
-            if (data.components?.schemas) {
-                console.log('Schemas count:', Object.keys(data.components.schemas).length);
-            }
-            else {
-                console.log('No schemas in loaded data');
+        const isRemoteInput = /^https?:\/\//i.test(input);
+        const resolveOptions = isRemoteInput
+            ? {
+                file: false,
+                http: {
+                    timeout: 15000,
+                    safeUrlResolver: false
+                }
             }
-            return data;
+            : {
+                http: {
+                    timeout: 15000,
+                    safeUrlResolver: false
+                }
+            };
+        const data = (await OpenAPIParser.bundle(input, {
+            resolve: resolveOptions
+        }));
+        if (isRemoteInput) {
+            logger_1.logger.debug(`从 URL 加载: ${input}`);
+        }
+        else {
+            logger_1.logger.debug(`从文件加载: ${path.resolve(input)}`);
+        }
+        if (data.components?.schemas) {
+            logger_1.logger.debugKV('schemas 数量', Object.keys(data.components.schemas).length);
+        }
+        else {
+            logger_1.logger.debug('加载的数据中未发现 schemas');
         }
-        const content = fs.readFileSync(input, 'utf-8');
-        return JSON.parse(content);
+        return data;
     }
     catch (error) {
-        throw new Error(`Failed to load Swagger document from ${input}: ${error}`);
+        throw new Error(`Failed to load OpenAPI document from ${input}: ${error}`);
     }
 }
 /**

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 {};