swagger2api-v3 1.1.7 → 1.1.8

package/README.md

@@ -37,7 +37,8 @@ The tool generates a `.swagger.config.json` configuration file:
 
 ```json
 {
-  "input": "https://petstore.swagger.io/v2/swagger.json",
+  "$schema": "./node_modules/swagger2api-v3/dist/.swagger2api.schema.json",
+  "input": "https://petstore3.swagger.io/api/v3/openapi.json",
   "output": "./src/api",
   "importTemplate": "import { request } from '@/utils/request';",
   "generator": "typescript",
@@ -48,6 +49,15 @@ The tool generates a `.swagger.config.json` configuration file:
   "lint": "prettier --write",
   "methodNameIgnorePrefix": [],
   "addMethodSuffix": true,
+  "headerComment": "",
+  "filter": {
+    "include": {
+      "tags": []
+    },
+    "exclude": {
+      "tags": []
+    }
+  },
   "options": {
     "addComments": true
   }
@@ -64,6 +74,7 @@ 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                | -              | Swagger JSON file path or URL                                                                                                                                      |
 | `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                                 |
@@ -75,6 +86,9 @@ npx swagger2api-v3 generate
 | `lint`                   | string                | -              | Code formatting command (optional)                                                                                                                                 |
 | `methodNameIgnorePrefix` | string[]              | `[]`           | Array of prefixes to ignore when generating method names. For example, `['api', 'auth']` will transform `apiGetName` to `getName` and `authUserInfo` to `userInfo` |
 | `addMethodSuffix`        | boolean               | `true`         | Whether to add HTTP method suffix to generated function names. `true` generates `userListPost`, `false` generates `userList`                                       |
+| `headerComment`          | string                | -              | Custom header comment for generated `types`, API, and index files                                                                                                  |
+| `filter.include.tags`    | string[]              | `[]`           | Only generate APIs whose tags match this list. Empty means include all                                                                                             |
+| `filter.exclude.tags`    | string[]              | `[]`           | Skip APIs whose tags match this list. Exclude rules take priority over include rules                                                                               |
 | `options.addComments`    | boolean               | `true`         | Whether to add detailed comments                                                                                                                                   |
 
 ## 📁 Generated File Structure

package/dist/.swagger2api.schema.json

@@ -0,0 +1,120 @@
+{
+  "title": "swagger2api-v3 config",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["input", "output", "generator", "groupByTags"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "本地 JSON Schema 路径，用于编辑器提示"
+    },
+    "input": {
+      "type": "string",
+      "description": "OpenAPI JSON 文件路径或 URL"
+    },
+    "output": {
+      "type": "string",
+      "description": "生成代码输出目录"
+    },
+    "generator": {
+      "enum": ["typescript", "javascript"],
+      "description": "生成器类型"
+    },
+    "groupByTags": {
+      "type": "boolean",
+      "description": "是否按 tags 分组生成文件"
+    },
+    "overwrite": {
+      "type": "boolean",
+      "description": "生成前是否覆盖输出目录"
+    },
+    "prefix": {
+      "type": "string",
+      "description": "接口路径公共前缀"
+    },
+    "requestStyle": {
+      "enum": ["method", "generic"],
+      "description": "请求调用风格"
+    },
+    "importTemplate": {
+      "type": "string",
+      "description": "request 导入语句"
+    },
+    "lint": {
+      "type": "string",
+      "description": "生成后执行的格式化命令"
+    },
+    "methodNameIgnorePrefix": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "生成方法名时需要忽略的前缀"
+    },
+    "addMethodSuffix": {
+      "type": "boolean",
+      "description": "是否在方法名中追加 HTTP method 后缀"
+    },
+    "headerComment": {
+      "type": "string",
+      "description": "自定义生成文件头部注释"
+    },
+    "filter": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "include": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "tags": {
+              "type": "array",
+              "items": { "type": "string" }
+            }
+          }
+        },
+        "exclude": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "tags": {
+              "type": "array",
+              "items": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "tagGrouping": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "createSubDirectories": { "type": "boolean" },
+        "fileNaming": {
+          "enum": ["tag", "kebab-case", "camelCase"]
+        }
+      }
+    },
+    "options": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "generateModels": { "type": "boolean" },
+        "generateApis": { "type": "boolean" },
+        "generateIndex": { "type": "boolean" },
+        "useAxios": { "type": "boolean" },
+        "addComments": { "type": "boolean" },
+        "prettify": { "type": "boolean" }
+      }
+    },
+    "comments": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "includeDescription": { "type": "boolean" },
+        "includeParameters": { "type": "boolean" },
+        "includeResponses": { "type": "boolean" },
+        "includeExamples": { "type": "boolean" }
+      }
+    }
+  }
+}

package/dist/cli/index.js

@@ -93,29 +93,12 @@ program
     .option('-f, --force', '强制覆盖已存在的配置文件')
     .action(async (options) => {
     const configPath = path.resolve(process.cwd(), '.swagger.config.json');
-    if (fs.existsSync(configPath) && !options.force) {
-        console.error('❌ 配置文件已存在，使用 --force 参数强制覆盖');
-        process.exit(1);
-    }
-    const config = {
-        input: 'http://localhost:3000/admin/docs/json',
-        output: './src/api',
-        importTemplate: "import { request } from '@/utils/request';",
-        generator: 'typescript',
-        requestStyle: 'generic',
-        groupByTags: true,
-        overwrite: true,
-        prefix: '',
-        lint: 'prettier --write',
-        methodNameIgnorePrefix: [],
-        addMethodSuffix: true,
-        options: {
-            addComments: true
-        }
-    };
     try {
+        const existsBeforeInit = fs.existsSync(configPath);
+        const config = createInitConfig(configPath, options.force);
+        const successMessage = getInitSuccessMessage(existsBeforeInit, options.force);
         fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
-        console.log('✅ 配置文件已创建:', configPath);
+        console.log(successMessage, configPath);
         console.log('💡 请根据需要修改配置文件，然后运行 swagger2api-v3 generate');
     }
     catch (error) {
@@ -137,21 +120,14 @@ program
         }
         const configContent = fs.readFileSync(configPath, 'utf-8');
         const config = JSON.parse(configContent);
-        const { Swagger2API } = await Promise.resolve().then(() => __importStar(require('../index')));
-        const swagger2api = new Swagger2API(config);
-        if (swagger2api.validateConfig()) {
+        const { validateSwaggerConfig } = await Promise.resolve().then(() => __importStar(require('../config/validator')));
+        const errors = validateSwaggerConfig(config);
+        if (errors.length === 0) {
             console.log('✅ 配置文件验证通过');
-            // 尝试加载 Swagger 文档
-            try {
-                const { loadSwaggerDocument } = await Promise.resolve().then(() => __importStar(require('../utils')));
-                const document = await loadSwaggerDocument(config.input);
-                console.log(`✅ Swagger 文档加载成功: ${document.info.title} v${document.info.version}`);
-            }
-            catch (error) {
-                console.warn('⚠️  Swagger 文档加载失败:', error);
-            }
         }
         else {
+            console.error('❌ 配置验证失败:');
+            errors.forEach((error) => console.error(`   - ${error}`));
             process.exit(1);
         }
     }
@@ -166,23 +142,119 @@ program
         process.exit(1);
     }
 });
-// run 命令（别名，兼容性）
-program
-    .command('run')
-    .description('运行生成器（generate 命令的别名）')
-    .option('-c, --config <path>', '配置文件路径', '.swagger.config.json')
-    .action(async (options) => {
-    try {
-        await (0, index_1.generateFromConfig)(options.config);
-    }
-    catch (error) {
-        console.error('❌ 生成失败:', error);
-        process.exit(1);
-    }
-});
 // 解析命令行参数
 program.parse();
 // 如果没有提供命令，显示帮助信息
 if (!process.argv.slice(2).length) {
     program.outputHelp();
 }
+/**
+ * 创建 init 命令需要写入的配置
+ * @param configPath 配置文件路径
+ * @param force 是否强制覆盖
+ * @returns 初始化配置对象
+ */
+function createInitConfig(configPath, force) {
+    const defaultConfig = createDefaultConfig();
+    if (!fs.existsSync(configPath) || force) {
+        return defaultConfig;
+    }
+    const existingConfig = readExistingConfig(configPath);
+    return mergeMissingConfig(existingConfig, defaultConfig);
+}
+/**
+ * 创建默认配置对象
+ * @returns 默认配置对象
+ */
+function createDefaultConfig() {
+    return {
+        $schema: './node_modules/swagger2api-v3/dist/.swagger2api.schema.json',
+        input: 'http://localhost:3000/admin/docs/json',
+        output: './src/api',
+        importTemplate: "import { request } from '@/utils/request';",
+        generator: 'typescript',
+        requestStyle: 'generic',
+        groupByTags: true,
+        overwrite: true,
+        prefix: '',
+        lint: 'prettier --write',
+        methodNameIgnorePrefix: [],
+        addMethodSuffix: true,
+        headerComment: '',
+        filter: {
+            include: {
+                tags: []
+            },
+            exclude: {
+                tags: []
+            }
+        },
+        options: {
+            addComments: true
+        }
+    };
+}
+/**
+ * 获取 init 命令成功提示
+ * @param existsBeforeInit 执行 init 前配置文件是否存在
+ * @param force 是否强制覆盖
+ * @returns 成功提示文案
+ */
+function getInitSuccessMessage(existsBeforeInit, force) {
+    if (existsBeforeInit && force) {
+        return '✅ 配置文件已覆盖:';
+    }
+    if (existsBeforeInit) {
+        return '✅ 配置文件已补全:';
+    }
+    return '✅ 配置文件已创建:';
+}
+/**
+ * 读取已存在的配置文件
+ * @param configPath 配置文件路径
+ * @returns 已存在的配置对象
+ */
+function readExistingConfig(configPath) {
+    try {
+        const configContent = fs.readFileSync(configPath, 'utf-8');
+        return JSON.parse(configContent);
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            console.error(`❌ 配置文件 JSON 格式错误: ${configPath}`);
+            console.error('错误详情:', error.message);
+        }
+        else {
+            console.error('❌ 读取配置文件失败:', error);
+        }
+        process.exit(1);
+        throw error;
+    }
+}
+/**
+ * 合并缺失的配置字段，保留已有配置值
+ * @param current 当前配置
+ * @param defaults 默认配置
+ * @returns 补全后的配置
+ */
+function mergeMissingConfig(current, defaults) {
+    const result = { ...current };
+    for (const [key, value] of Object.entries(defaults)) {
+        if (result[key] === undefined) {
+            result[key] = value;
+            continue;
+        }
+        if (isPlainObject(result[key]) && isPlainObject(value)) {
+            result[key] = mergeMissingConfig(result[key], value);
+        }
+    }
+    return result;
+}
+/**
+ * 判断是否为普通对象
+ * @param value 待判断的值
+ * @returns 是否为普通对象
+ */
+function isPlainObject(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}

package/dist/config/validator.d.ts

@@ -0,0 +1,7 @@
+import { SwaggerConfig } from '../types';
+/**
+ * 验证配置对象
+ * @param config 配置对象
+ * @returns 错误信息数组
+ */
+export declare function validateSwaggerConfig(config: SwaggerConfig): string[];

package/dist/config/validator.js

@@ -0,0 +1,218 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateSwaggerConfig = validateSwaggerConfig;
+const CONFIG_KEYS = [
+    '$schema',
+    'input',
+    'output',
+    'generator',
+    'groupByTags',
+    'overwrite',
+    'prefix',
+    'requestStyle',
+    'tagGrouping',
+    'options',
+    'comments',
+    'importTemplate',
+    'lint',
+    'methodNameIgnorePrefix',
+    'addMethodSuffix',
+    'filter',
+    'headerComment'
+];
+const OPTIONS_KEYS = [
+    'generateModels',
+    'generateApis',
+    'generateIndex',
+    'useAxios',
+    'addComments',
+    'prettify'
+];
+const TAG_GROUPING_KEYS = ['enabled', 'createSubDirectories', 'fileNaming'];
+const COMMENT_KEYS = [
+    'includeDescription',
+    'includeParameters',
+    'includeResponses',
+    'includeExamples'
+];
+/**
+ * 验证配置对象
+ * @param config 配置对象
+ * @returns 错误信息数组
+ */
+function validateSwaggerConfig(config) {
+    const errors = [];
+    validateRequiredString(config.input, 'input', errors);
+    validateRequiredString(config.output, 'output', errors);
+    validateEnum(config.generator, 'generator', ['typescript', 'javascript'], errors);
+    validateBoolean(config.groupByTags, 'groupByTags', errors);
+    validateOptionalBoolean(config.overwrite, 'overwrite', errors);
+    validateOptionalString(config.prefix, 'prefix', errors);
+    validateOptionalString(config.importTemplate, 'importTemplate', errors);
+    validateOptionalString(config.lint, 'lint', errors);
+    validateOptionalString(config.headerComment, 'headerComment', errors);
+    validateOptionalString(config.$schema, '$schema', errors);
+    validateOptionalBoolean(config.addMethodSuffix, 'addMethodSuffix', errors);
+    validateOptionalEnum(config.requestStyle, 'requestStyle', ['method', 'generic'], errors);
+    validateStringArray(config.methodNameIgnorePrefix, 'methodNameIgnorePrefix', errors);
+    validateFilter(config, errors);
+    validateOptions(config, errors);
+    validateTagGrouping(config, errors);
+    validateComments(config, errors);
+    validateKnownKeys(config, CONFIG_KEYS, 'config', errors);
+    return errors;
+}
+/**
+ * 验证必填字符串
+ * @param value 字段值
+ * @param field 字段名
+ * @param errors 错误信息数组
+ */
+function validateRequiredString(value, field, errors) {
+    if (typeof value !== 'string' || !value) {
+        errors.push(`${field} 配置项不能为空，且必须是字符串`);
+    }
+}
+/**
+ * 验证可选字符串
+ * @param value 字段值
+ * @param field 字段名
+ * @param errors 错误信息数组
+ */
+function validateOptionalString(value, field, errors) {
+    if (value !== undefined && typeof value !== 'string') {
+        errors.push(`${field} 必须是字符串`);
+    }
+}
+/**
+ * 验证布尔值
+ * @param value 字段值
+ * @param field 字段名
+ * @param errors 错误信息数组
+ */
+function validateBoolean(value, field, errors) {
+    if (typeof value !== 'boolean') {
+        errors.push(`${field} 必须是布尔值`);
+    }
+}
+/**
+ * 验证可选布尔值
+ * @param value 字段值
+ * @param field 字段名
+ * @param errors 错误信息数组
+ */
+function validateOptionalBoolean(value, field, errors) {
+    if (value !== undefined && typeof value !== 'boolean') {
+        errors.push(`${field} 必须是布尔值`);
+    }
+}
+/**
+ * 验证枚举值
+ * @param value 字段值
+ * @param field 字段名
+ * @param values 允许值
+ * @param errors 错误信息数组
+ */
+function validateEnum(value, field, values, errors) {
+    if (typeof value !== 'string' || !values.includes(value)) {
+        errors.push(`${field} 必须是 ${values.join(' 或 ')}`);
+    }
+}
+/**
+ * 验证可选枚举值
+ * @param value 字段值
+ * @param field 字段名
+ * @param values 允许值
+ * @param errors 错误信息数组
+ */
+function validateOptionalEnum(value, field, values, errors) {
+    if (value !== undefined) {
+        validateEnum(value, field, values, errors);
+    }
+}
+/**
+ * 验证字符串数组
+ * @param value 字段值
+ * @param field 字段名
+ * @param errors 错误信息数组
+ */
+function validateStringArray(value, field, errors) {
+    if (value === undefined)
+        return;
+    if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+        errors.push(`${field} 必须是字符串数组`);
+    }
+}
+/**
+ * 验证过滤配置
+ * @param config 配置对象
+ * @param errors 错误信息数组
+ */
+function validateFilter(config, errors) {
+    if (!config.filter)
+        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);
+}
+/**
+ * 验证生成选项配置
+ * @param config 配置对象
+ * @param errors 错误信息数组
+ */
+function validateOptions(config, errors) {
+    if (!config.options)
+        return;
+    validateKnownKeys(config.options, OPTIONS_KEYS, 'options', errors);
+    validateOptionalBoolean(config.options.generateModels, 'options.generateModels', errors);
+    validateOptionalBoolean(config.options.generateApis, 'options.generateApis', errors);
+    validateOptionalBoolean(config.options.generateIndex, 'options.generateIndex', errors);
+    validateOptionalBoolean(config.options.useAxios, 'options.useAxios', errors);
+    validateOptionalBoolean(config.options.addComments, 'options.addComments', errors);
+    validateOptionalBoolean(config.options.prettify, 'options.prettify', errors);
+}
+/**
+ * 验证标签分组选项
+ * @param config 配置对象
+ * @param errors 错误信息数组
+ */
+function validateTagGrouping(config, errors) {
+    if (!config.tagGrouping)
+        return;
+    validateKnownKeys(config.tagGrouping, TAG_GROUPING_KEYS, 'tagGrouping', errors);
+    validateOptionalBoolean(config.tagGrouping.enabled, 'tagGrouping.enabled', errors);
+    validateOptionalBoolean(config.tagGrouping.createSubDirectories, 'tagGrouping.createSubDirectories', errors);
+    validateOptionalEnum(config.tagGrouping.fileNaming, 'tagGrouping.fileNaming', ['tag', 'kebab-case', 'camelCase'], errors);
+}
+/**
+ * 验证注释配置
+ * @param config 配置对象
+ * @param errors 错误信息数组
+ */
+function validateComments(config, errors) {
+    if (!config.comments)
+        return;
+    validateKnownKeys(config.comments, COMMENT_KEYS, 'comments', errors);
+    validateOptionalBoolean(config.comments.includeDescription, 'comments.includeDescription', errors);
+    validateOptionalBoolean(config.comments.includeParameters, 'comments.includeParameters', errors);
+    validateOptionalBoolean(config.comments.includeResponses, 'comments.includeResponses', errors);
+    validateOptionalBoolean(config.comments.includeExamples, 'comments.includeExamples', errors);
+}
+/**
+ * 验证未知字段
+ * @param value 对象值
+ * @param knownKeys 允许字段列表
+ * @param path 对象路径
+ * @param errors 错误信息数组
+ */
+function validateKnownKeys(value, knownKeys, path, errors) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return;
+    for (const key of Object.keys(value)) {
+        if (!knownKeys.includes(key)) {
+            errors.push(`${path}.${key} 不是支持的配置项`);
+        }
+    }
+}

package/dist/core/generator.d.ts

@@ -51,7 +51,7 @@ export declare class CodeGenerator {
     private generateApiFunction;
     /**
      * 生成直接参数形式
-     * @param parameters Swagger参数数组
+     * @param parameters OpenAPI 参数数组
      * @returns 函数参数字符串
      */
     private generateDirectParameters;
@@ -104,6 +104,12 @@ export declare class CodeGenerator {
      * @returns 文件名
      */
     private getTagFileName;
+    /**
+     * 生成文件头部注释
+     * @param defaultHeader 默认头部注释
+     * @returns 文件头部注释内容
+     */
+    private generateHeader;
     /**
      * 在所有文件生成完成后运行lint命令
      */