swagger2api-v3 1.1.10 → 1.1.11

package/README.md

@@ -2,11 +2,11 @@
 
 English | [中文](./README_CN.md)
 
-A powerful command-line tool for automatically generating TypeScript or JavaScript interface code from OpenAPI 3.x / Swagger 3.0 documentation.
+A powerful command-line tool for automatically generating TypeScript or JavaScript interface code from OpenAPI 3.0 documentation.
 
 ## ✨ Features
 
-- 🚀 **Fast Generation** - Quickly generate TypeScript interface code from OpenAPI/Swagger 3.0 JSON
+- 🚀 **Fast Generation** - Quickly generate TypeScript interface code from OpenAPI 3.0 JSON or YAML
 - 📁 **Smart Grouping** - Support automatic file grouping by document tags
 - 📝 **Detailed Comments** - Automatically generate detailed comments including descriptions, parameters, and return values
 - 🎨 **Code Formatting** - Support custom formatting commands
@@ -76,11 +76,11 @@ npx swagger2api-v3 generate
 | Option                   | Type                  | Default        | Description                                                                                                                                                        |
 | ------------------------ | --------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `$schema`                | string                | -              | Local JSON Schema path for editor completion. The default points to `node_modules/swagger2api-v3/dist/.swagger2api.schema.json`                                    |
-| `input`                  | string                | -              | OpenAPI/Swagger 3.0 JSON file path or URL                                                                                                                          |
+| `input`                  | string                | -              | OpenAPI 3.0 JSON/YAML file path or URL; local and remote external `$ref` references are bundled automatically                                                      |
 | `output`                 | string                | `'./src/api'`  | Output directory for generated code                                                                                                                                |
 | `generator`              | string                | `'typescript'` | Code generator type. Supports `'typescript'` and `'javascript'`. `'javascript'` outputs `.js` files and skips type file generation                                 |
 | `groupByTags`            | boolean               | `true`         | Whether to group files by tags                                                                                                                                     |
-| `multiTagStrategy`       | 'first' \| 'all'      | `'first'`      | Grouping strategy for operations with multiple tags. `first` uses only the first tag, `all` combines all tags into one group name                                    |
+| `multiTagStrategy`       | 'first' \| 'all'      | `'first'`      | Grouping strategy for operations with multiple tags. `first` uses only the first tag, `all` combines all tags into one group name                                  |
 | `overwrite`              | boolean               | `true`         | Whether to overwrite existing files                                                                                                                                |
 | `prefix`                 | string                | `''`           | Common prefix for API paths                                                                                                                                        |
 | `importTemplate`         | string                | -              | Import statement template for request function                                                                                                                     |

package/dist/.swagger2api.schema.json

@@ -10,11 +10,11 @@
     },
     "input": {
       "type": "string",
-      "description": "OpenAPI JSON 文件路径或 URL"
+      "description": "OpenAPI 3.0 JSON/YAML 文件路径或 URL"
     },
     "output": {
       "type": "string",
-      "description": "生成代码输出目录"
+      "description": "生成代码输出目录，不能是当前工作目录或其父目录"
     },
     "generator": {
       "enum": ["typescript", "javascript"],

package/dist/cli/index.js

@@ -44,7 +44,7 @@ const program = new commander_1.Command();
 const packageJson = JSON.parse(fs.readFileSync(path.join(__dirname, '../../package.json'), 'utf-8'));
 program
     .name('swagger2api-v3')
-    .description('从 Swagger/OpenAPI 文档生成 TypeScript API 接口')
+    .description('从 OpenAPI 3.0 文档生成 TypeScript API 接口')
     .version(packageJson.version);
 // generate 命令
 program
@@ -52,7 +52,7 @@ program
     .alias('gen')
     .description('根据配置文件生成 API 接口')
     .option('-c, --config <path>', '配置文件路径', '.swagger.config.json')
-    .option('-i, --input <path>', 'Swagger JSON 文件路径或 URL')
+    .option('-i, --input <path>', 'OpenAPI JSON/YAML 文件路径或 URL')
     .option('-o, --output <path>', '输出目录')
     .option('--no-types', '不生成类型文件')
     .option('--no-group', '不按标签分组')

package/dist/config/validator.js

@@ -1,6 +1,41 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateSwaggerConfig = validateSwaggerConfig;
+const path = __importStar(require("path"));
+const file_1 = require("../utils/file");
 const CONFIG_KEYS = [
     '$schema',
     'input',
@@ -43,8 +78,12 @@ const COMMENT_KEYS = [
  */
 function validateSwaggerConfig(config) {
     const errors = [];
+    if (!isPlainObject(config)) {
+        return ['config 必须是对象'];
+    }
     validateRequiredString(config.input, 'input', errors);
     validateRequiredString(config.output, 'output', errors);
+    validateOutputPath(config.output, errors);
     validateEnum(config.generator, 'generator', ['typescript', 'javascript'], errors);
     validateBoolean(config.groupByTags, 'groupByTags', errors);
     validateOptionalEnum(config.multiTagStrategy, 'multiTagStrategy', ['first', 'all'], errors);
@@ -71,10 +110,25 @@ function validateSwaggerConfig(config) {
  * @param errors 错误信息数组
  */
 function validateRequiredString(value, field, errors) {
-    if (typeof value !== 'string' || !value) {
+    if (typeof value !== 'string' || !value.trim()) {
         errors.push(`${field} 配置项不能为空，且必须是字符串`);
     }
 }
+/**
+ * 验证输出路径不会覆盖当前工作目录或其父目录
+ * @param value 输出路径
+ * @param errors 错误信息数组
+ */
+function validateOutputPath(value, errors) {
+    if (typeof value !== 'string' || !value.trim())
+        return;
+    const currentDirectory = path.resolve(process.cwd());
+    const outputDirectory = path.resolve(currentDirectory, value);
+    if (outputDirectory === currentDirectory ||
+        (0, file_1.isPathInside)(outputDirectory, currentDirectory)) {
+        errors.push('output 不能是当前工作目录或其父目录');
+    }
+}
 /**
  * 验证可选字符串
  * @param value 字段值
@@ -151,13 +205,17 @@ function validateStringArray(value, field, errors) {
  * @param errors 错误信息数组
  */
 function validateFilter(config, errors) {
-    if (!config.filter)
+    if (!validateOptionalPlainObject(config.filter, 'filter', errors))
         return;
     validateKnownKeys(config.filter, ['include', 'exclude'], 'filter', errors);
-    validateKnownKeys(config.filter.include, ['tags'], 'filter.include', errors);
-    validateKnownKeys(config.filter.exclude, ['tags'], 'filter.exclude', errors);
-    validateStringArray(config.filter.include?.tags, 'filter.include.tags', errors);
-    validateStringArray(config.filter.exclude?.tags, 'filter.exclude.tags', errors);
+    if (validateOptionalPlainObject(config.filter.include, 'filter.include', errors)) {
+        validateKnownKeys(config.filter.include, ['tags'], 'filter.include', errors);
+        validateStringArray(config.filter.include.tags, 'filter.include.tags', errors);
+    }
+    if (validateOptionalPlainObject(config.filter.exclude, 'filter.exclude', errors)) {
+        validateKnownKeys(config.filter.exclude, ['tags'], 'filter.exclude', errors);
+        validateStringArray(config.filter.exclude.tags, 'filter.exclude.tags', errors);
+    }
 }
 /**
  * 验证生成选项配置
@@ -165,7 +223,7 @@ function validateFilter(config, errors) {
  * @param errors 错误信息数组
  */
 function validateOptions(config, errors) {
-    if (!config.options)
+    if (!validateOptionalPlainObject(config.options, 'options', errors))
         return;
     validateKnownKeys(config.options, OPTIONS_KEYS, 'options', errors);
     validateOptionalBoolean(config.options.generateModels, 'options.generateModels', errors);
@@ -181,8 +239,9 @@ function validateOptions(config, errors) {
  * @param errors 错误信息数组
  */
 function validateTagGrouping(config, errors) {
-    if (!config.tagGrouping)
+    if (!validateOptionalPlainObject(config.tagGrouping, 'tagGrouping', errors)) {
         return;
+    }
     validateKnownKeys(config.tagGrouping, TAG_GROUPING_KEYS, 'tagGrouping', errors);
     validateOptionalBoolean(config.tagGrouping.enabled, 'tagGrouping.enabled', errors);
     validateOptionalBoolean(config.tagGrouping.createSubDirectories, 'tagGrouping.createSubDirectories', errors);
@@ -194,7 +253,7 @@ function validateTagGrouping(config, errors) {
  * @param errors 错误信息数组
  */
 function validateComments(config, errors) {
-    if (!config.comments)
+    if (!validateOptionalPlainObject(config.comments, 'comments', errors))
         return;
     validateKnownKeys(config.comments, COMMENT_KEYS, 'comments', errors);
     validateOptionalBoolean(config.comments.includeDescription, 'comments.includeDescription', errors);
@@ -218,3 +277,27 @@ function validateKnownKeys(value, knownKeys, path, errors) {
         }
     }
 }
+/**
+ * 验证可选配置值是否为普通对象
+ * @param value 配置值
+ * @param field 字段路径
+ * @param errors 错误信息数组
+ * @returns 配置值是否为普通对象
+ */
+function validateOptionalPlainObject(value, field, errors) {
+    if (value === undefined)
+        return false;
+    if (!isPlainObject(value)) {
+        errors.push(`${field} 必须是对象`);
+        return false;
+    }
+    return true;
+}
+/**
+ * 判断值是否为普通对象
+ * @param value 待判断的值
+ * @returns 是否为普通对象
+ */
+function isPlainObject(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}

package/dist/core/generator.d.ts

@@ -4,6 +4,11 @@ import { SwaggerConfig, ApiInfo, TypeInfo } from '../types';
  */
 export declare class CodeGenerator {
     private config;
+    private readonly outputRoot;
+    /**
+     * 创建代码生成器
+     * @param config 生成配置
+     */
     constructor(config: SwaggerConfig);
     /**
      * 生成所有文件
@@ -23,6 +28,31 @@ export declare class CodeGenerator {
      * @returns 类型文件内容
      */
     private generateTypesContent;
+    /**
+     * 渲染类型定义列表
+     * @param types 类型定义数组
+     * @returns 类型定义内容
+     */
+    private renderTypeDefinitions;
+    /**
+     * 合并类型定义
+     * @param modelTypes 组件模型类型
+     * @param parameterTypes 查询参数类型
+     * @returns 合并后的类型定义
+     */
+    private mergeTypeDefinitions;
+    /**
+     * 判断是否应提取查询参数类型
+     * @returns 是否提取查询参数类型
+     */
+    private shouldExtractQueryParameterTypes;
+    /**
+     * 生成 tag 内的查询参数类型文件
+     * @param folderName tag 目录名
+     * @param apis 当前 tag 的 API 接口
+     * @param modelTypes 组件模型类型
+     */
+    private generateTagParameterTypesFile;
     /**
      * 按标签生成API文件
      * @param groupedApis 按标签分组的API
@@ -46,31 +76,35 @@ export declare class CodeGenerator {
     /**
      * 生成单个API函数
      * @param api API接口信息
+     * @param queryParameterTypeName 查询参数类型名
      * @returns API函数代码
      */
     private generateApiFunction;
     /**
      * 生成直接参数形式
      * @param parameters OpenAPI 参数数组
+     * @param isJavaScript 是否生成 JavaScript 参数
+     * @param queryParameterTypeName 查询参数类型名
      * @returns 函数参数字符串
      */
     private generateDirectParameters;
-    /**
-     * 从schema获取类型
-     * @param schema Swagger schema
-     * @returns 类型字符串
-     */
-    private getTypeFromSchema;
     /**
      * 获取当前配置下可安全输出的类型
      * @param type 类型字符串
      * @returns 安全类型字符串
      */
     private getSafeGeneratedType;
+    /**
+     * 渲染内联查询参数类型成员
+     * @param parameters 查询参数数组
+     * @returns 内联类型成员
+     */
+    private renderInlineQueryParameterMembers;
     /**
      * 收集API数组中实际使用的类型
      * @param apis API接口数组
      * @param definedTypes 已定义的类型数组
+     * @param excludeQueryParameters 是否排除查询参数
      * @returns 使用的类型名称数组
      */
     private collectUsedTypes;
@@ -86,13 +120,6 @@ export declare class CodeGenerator {
      * @returns 是否为基础类型
      */
     private isPrimitiveType;
-    /**
-     * 检测是否为通用响应容器类型
-     * @param type 类型信息
-     * @param definition 类型定义
-     * @returns 是否为通用响应容器类型
-     */
-    private isGenericResponseContainer;
     /**
      * 生成请求配置
      * @param api API接口信息
@@ -100,16 +127,26 @@ export declare class CodeGenerator {
      */
     private generateRequestConfig;
     /**
-     * 生成 params 对象字段访问表达式
-     * @param name 参数名
-     * @returns 字段访问表达式
+     * 创建不重复的路径参数变量名
+     * @param parameters OpenAPI 路径参数
+     * @returns 路径参数变量名
      */
-    private getParamAccessExpression;
+    private createPathParameterNames;
     /**
      * 生成入口文件
      * @param groupedApis 按标签分组的API
      */
     private generateIndexFile;
+    /**
+     * 校验输出目录不会覆盖当前工作目录或其父目录
+     */
+    private assertSafeOutputDirectory;
+    /**
+     * 解析并校验输出目录内的文件路径
+     * @param segments 输出目录下的路径片段
+     * @returns 安全的绝对路径
+     */
+    private resolveOutputPath;
     /**
      * 写入生成文件，overwrite=false 时保留已存在文件
      * @param filePath 文件路径
@@ -122,6 +159,23 @@ export declare class CodeGenerator {
      * @returns 文件名
      */
     private getTagFileName;
+    /**
+     * 校验所有标签生成的目录名称安全且不重复
+     * @param groupedApis 按标签分组的 API
+     */
+    private validateTagFolders;
+    /**
+     * 转义模板字符串中的特殊字符
+     * @param value 原始字符串
+     * @returns 可安全写入模板字符串的内容
+     */
+    private escapeTemplateLiteral;
+    /**
+     * 将字符串转换为安全的单引号字面量
+     * @param value 原始字符串
+     * @returns 单引号字符串字面量
+     */
+    private toSingleQuotedString;
     /**
      * 生成文件头部注释
      * @param defaultHeader 默认头部注释