swagger2api-v3 1.1.4 → 1.1.6

package/README.md

@@ -2,7 +2,7 @@
 
 English | [中文](./README_CN.md)
 
-A powerful command-line tool for automatically generating TypeScript interface code from Swagger (OAS3.0) documentation.
+A powerful command-line tool for automatically generating TypeScript or JavaScript interface code from OpenAPI 3.0 documentation.
 
 ## ✨ Features
 
@@ -33,36 +33,25 @@ npx swagger2api-v3 init
 
 ### 2. Configuration File Description
 
-The tool automatically generates configuration files in the corresponding format based on the project environment:
+The tool generates a `.swagger.config.json` configuration file:
 
-**CommonJS Environment** (`"type": "commonjs"` or not set):
-
-```javascript
-const config = {
-  input: 'https://petstore.swagger.io/v2/swagger.json',
-  output: './src/api',
-  importTemplate: "import { request } from '@/utils/request';",
-  generator: 'typescript',
-  groupByTags: true,
-  overwrite: true,
-  prefix: '',
-  lint: 'prettier --write',
-  options: {
-    addComments: true
+```json
+{
+  "input": "https://petstore.swagger.io/v2/swagger.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
   }
-};
-
-module.exports = config;
-```
-
-**ES Module Environment** (`"type": "module"`):
-
-```javascript
-const config = {
-  // ... same configuration
-};
-
-export default config;
+}
 ```
 
 ### 3. Generate Interface Code
@@ -226,12 +215,10 @@ Add to `package.json`:
 
 Support automatic execution of formatting commands after generation:
 
-```javascript
-// In configuration file
-const config = {
-  // ... other configurations
-  lint: 'prettier --write' // or 'eslint --fix', etc.
-};
+```json
+{
+  "lint": "prettier --write"
+}
 ```
 
 ## 🤝 Contributing

package/dist/cli/index.js

@@ -50,7 +50,7 @@ program
     .command('generate')
     .alias('gen')
     .description('根据配置文件生成 API 接口')
-    .option('-c, --config <path>', '配置文件路径', '.swagger.config.ts')
+    .option('-c, --config <path>', '配置文件路径', '.swagger.config.json')
     .option('-i, --input <path>', 'Swagger JSON 文件路径或 URL')
     .option('-o, --output <path>', '输出目录')
     .option('--no-types', '不生成类型文件')
@@ -92,79 +92,31 @@ program
     .description('初始化配置文件')
     .option('-f, --force', '强制覆盖已存在的配置文件')
     .action(async (options) => {
-    const configPath = path.resolve(process.cwd(), '.swagger.config.ts');
+    const configPath = path.resolve(process.cwd(), '.swagger.config.json');
     if (fs.existsSync(configPath) && !options.force) {
         console.error('❌ 配置文件已存在，使用 --force 参数强制覆盖');
         process.exit(1);
     }
-    // 检测当前项目的模块类型
-    let isESModule = true; // 默认使用 ES Module
-    const packageJsonPath = path.resolve(process.cwd(), 'package.json');
-    if (fs.existsSync(packageJsonPath)) {
-        try {
-            const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
-            // 只有明确设置为 commonjs 时才使用 CommonJS，否则默认使用 ES Module
-            isESModule = packageJson.type !== 'commonjs';
+    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
         }
-        catch (error) {
-            console.warn('⚠️ 无法读取package.json，使用默认ES Module格式');
-        }
-    }
-    const configContent = `/**
- * Swagger2API 配置文件
- * 用于配置从 Swagger JSON 生成前端接口的参数
- */
-const config = {
-  // Swagger JSON 文件路径或 URL
-  input: 'http://localhost:3000/admin/docs/json',
-  
-  // 输出目录
-  output: './src/api',
-  
-  // request 导入路径模板
-  importTemplate: "import { request } from '@/utils/request';",
-  
-  // 生成器类型
-  generator: 'typescript', // 可选 'javascript'（JS 模式输出 .js 文件且不生成类型文件）
-  
-  // 请求调用风格：'method' 使用 request.get/post；'generic' 使用 request({ method })
-  requestStyle: 'generic',
-  
-  // 按标签分组生成文件
-  groupByTags: true,
-  
-  // 是否覆盖更新，默认为true。为true时会先删除输出目录下的所有文件
-  overwrite: true,
-  
-  // 接口路径公共前缀，默认为空字符串
-  prefix: '',
-  
-  // 代码格式化命令（可选）
-  lint: 'prettier --write',
-  
-  // 生成方法名时需要忽略的前缀（可选）
-  // 例如：配置 ['api', 'auth'] 后，apiGetName 会变成 getName，authUserInfo 会变成 userInfo
-  // 如果方法名是 apiAuthGetName，会依次移除所有匹配的前缀，最终变成 getName
-  methodNameIgnorePrefix: [],
-  
-  // 是否在生成的方法名中添加 HTTP method 后缀，默认为 true
-  // true: userListPost, userDetailGet
-  // false: userList, userDetail
-  addMethodSuffix: true,
-  
-  // 生成选项
-  options: {
-    // 是否添加注释
-    addComments: true
-  }
-};
-
-${isESModule ? 'export default config;' : 'module.exports = config;'}
-`;
+    };
     try {
-        fs.writeFileSync(configPath, configContent, 'utf-8');
+        fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
         console.log('✅ 配置文件已创建:', configPath);
-        console.log('💡 请根据需要修改配置文件，然后运行 swagger2api generate');
+        console.log('💡 请根据需要修改配置文件，然后运行 swagger2api-v3 generate');
     }
     catch (error) {
         console.error('❌ 创建配置文件失败:', error);
@@ -175,12 +127,16 @@ ${isESModule ? 'export default config;' : 'module.exports = config;'}
 program
     .command('validate')
     .description('验证配置文件')
-    .option('-c, --config <path>', '配置文件路径', '.swagger.config.ts')
+    .option('-c, --config <path>', '配置文件路径', '.swagger.config.json')
     .action(async (options) => {
     const configPath = path.resolve(process.cwd(), options.config);
     try {
-        const configModule = await Promise.resolve(`${configPath}`).then(s => __importStar(require(s)));
-        const config = configModule.default || configModule;
+        if (!fs.existsSync(configPath)) {
+            console.error(`❌ 找不到配置文件: ${configPath}`);
+            process.exit(1);
+        }
+        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()) {
@@ -200,7 +156,13 @@ program
         }
     }
     catch (error) {
-        console.error('❌ 配置文件验证失败:', error);
+        if (error instanceof SyntaxError) {
+            console.error(`❌ 配置文件 JSON 格式错误: ${configPath}`);
+            console.error('错误详情:', error.message);
+        }
+        else {
+            console.error('❌ 配置文件验证失败:', error);
+        }
         process.exit(1);
     }
 });
@@ -208,7 +170,7 @@ program
 program
     .command('run')
     .description('运行生成器（generate 命令的别名）')
-    .option('-c, --config <path>', '配置文件路径', '.swagger.config.ts')
+    .option('-c, --config <path>', '配置文件路径', '.swagger.config.json')
     .action(async (options) => {
     try {
         await (0, index_1.generateFromConfig)(options.config);

package/dist/core/parser.js

@@ -180,7 +180,9 @@ class SwaggerParser {
             const properties = Object.entries(schema.properties)
                 .map(([key, value]) => {
                 const optional = schema.required?.includes(key) ? '' : '?';
-                const type = (0, utils_1.swaggerTypeToTsType)(value, allSchemas);
+                let type = (0, utils_1.swaggerTypeToTsType)(value, allSchemas);
+                if (optional === '?')
+                    type = (0, utils_1.stripNullFromUnion)(type);
                 const comment = value.description
                     ? ` /** ${value.description} */`
                     : '';
@@ -203,7 +205,9 @@ class SwaggerParser {
                 // 优先使用 x-enum-varnames 或 x-enumNames 扩展字段
                 if ((schema['x-enum-varnames'] && schema['x-enum-varnames'][index]) ||
                     (schema['x-enumNames'] && schema['x-enumNames'][index])) {
-                    key = schema['x-enum-varnames']?.[index] || schema['x-enumNames']?.[index];
+                    key =
+                        schema['x-enum-varnames']?.[index] ||
+                            schema['x-enumNames']?.[index];
                 }
                 else if (/^\d+$/.test(value)) {
                     // 对于数字枚举，使用 VALUE_ 前缀

package/dist/index.js

@@ -40,6 +40,7 @@ exports.CodeGenerator = exports.SwaggerParser = exports.Swagger2API = void 0;
 exports.generateFromConfig = generateFromConfig;
 exports.generate = generate;
 const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
 const parser_1 = require("./core/parser");
 const generator_1 = require("./core/generator");
 const utils_1 = require("./utils");
@@ -119,15 +120,19 @@ exports.Swagger2API = Swagger2API;
  * @param configPath 配置文件路径
  */
 async function generateFromConfig(configPath) {
-    const configFile = configPath || '.swagger.config.ts';
+    const configFile = configPath || '.swagger.config.json';
     const fullPath = path.resolve(process.cwd(), configFile);
     try {
         let config;
-        // 使用动态import加载配置文件以支持ES模块语法
-        const fileUrl = `file:///${fullPath.replace(/\\/g, '/')}?t=${Date.now()}`;
-        const dynamicImport = new Function('specifier', 'return import(specifier)');
-        const configModule = await dynamicImport(fileUrl);
-        config = configModule.default || configModule;
+        // 读取并解析 JSON 配置文件
+        if (!fs.existsSync(fullPath)) {
+            console.error(`❌ 找不到配置文件: ${fullPath}`);
+            console.error('请确保配置文件存在并且路径正确');
+            console.error('提示: 运行 swagger2api-v3 init 来创建配置文件');
+            process.exit(1);
+        }
+        const configContent = fs.readFileSync(fullPath, 'utf-8');
+        config = JSON.parse(configContent);
         const swagger2api = new Swagger2API(config);
         if (!swagger2api.validateConfig()) {
             process.exit(1);
@@ -135,10 +140,10 @@ async function generateFromConfig(configPath) {
         await swagger2api.generate();
     }
     catch (error) {
-        if (error instanceof Error &&
-            error.message.includes('Cannot resolve module')) {
-            console.error(`❌ 找不到配置文件: ${fullPath}`);
-            console.error('请确保配置文件存在并且路径正确');
+        if (error instanceof SyntaxError) {
+            console.error(`❌ 配置文件 JSON 格式错误: ${fullPath}`);
+            console.error('请检查 JSON 语法是否正确');
+            console.error('错误详情:', error.message);
         }
         else {
             console.error('❌ 加载配置文件失败:', error);

package/dist/utils/index.d.ts

@@ -41,6 +41,7 @@ export declare function stripMethodNamePrefixes(methodName: string, prefixes?: s
  * @returns 移除后缀后的函数名
  */
 export declare function removeMethodSuffix(functionName: string, method: string): string;
+export declare function stripNullFromUnion(typeStr: string): string;
 /**
  * 将Swagger类型转换为TypeScript类型
  * @param schema Swagger模式

package/dist/utils/index.js

@@ -42,6 +42,7 @@ exports.toPascalCase = toPascalCase;
 exports.toCamelCase = toCamelCase;
 exports.stripMethodNamePrefixes = stripMethodNamePrefixes;
 exports.removeMethodSuffix = removeMethodSuffix;
+exports.stripNullFromUnion = stripNullFromUnion;
 exports.swaggerTypeToTsType = swaggerTypeToTsType;
 exports.generateParameterTypes = generateParameterTypes;
 exports.ensureDirectoryExists = ensureDirectoryExists;
@@ -165,6 +166,49 @@ function removeMethodSuffix(functionName, method) {
     }
     return functionName;
 }
+function stripNullFromUnion(typeStr) {
+    if (!typeStr)
+        return 'any';
+    const parts = [];
+    let current = '';
+    let parenDepth = 0;
+    let angleDepth = 0;
+    let braceDepth = 0;
+    let bracketDepth = 0;
+    for (let i = 0; i < typeStr.length; i++) {
+        const ch = typeStr[i];
+        if (ch === '(')
+            parenDepth++;
+        else if (ch === ')')
+            parenDepth = Math.max(0, parenDepth - 1);
+        else if (ch === '<')
+            angleDepth++;
+        else if (ch === '>')
+            angleDepth = Math.max(0, angleDepth - 1);
+        else if (ch === '{')
+            braceDepth++;
+        else if (ch === '}')
+            braceDepth = Math.max(0, braceDepth - 1);
+        else if (ch === '[')
+            bracketDepth++;
+        else if (ch === ']')
+            bracketDepth = Math.max(0, bracketDepth - 1);
+        const isTopLevel = parenDepth === 0 &&
+            angleDepth === 0 &&
+            braceDepth === 0 &&
+            bracketDepth === 0;
+        if (ch === '|' && isTopLevel) {
+            parts.push(current.trim());
+            current = '';
+            continue;
+        }
+        current += ch;
+    }
+    if (current.trim())
+        parts.push(current.trim());
+    const normalized = Array.from(new Set(parts.filter((p) => p && p !== 'null')));
+    return normalized.length > 0 ? normalized.join(' | ') : 'any';
+}
 /**
  * 将Swagger类型转换为TypeScript类型
  * @param schema Swagger模式
@@ -190,7 +234,7 @@ function swaggerTypeToTsType(schema, schemas) {
                 // 这里假设泛型参数是 properties 中的第一个属性
                 const propertyTypes = [];
                 for (const [propName, propSchema] of Object.entries(secondSchema.properties)) {
-                    const propType = swaggerTypeToTsType(propSchema);
+                    const propType = swaggerTypeToTsType(propSchema, schemas);
                     propertyTypes.push(propType);
                 }
                 // 如果只有一个属性，直接作为泛型参数
@@ -202,7 +246,9 @@ function swaggerTypeToTsType(schema, schemas) {
                     const combinedType = `{ ${Object.entries(secondSchema.properties)
                         .map(([key, value]) => {
                         const optional = secondSchema.required?.includes(key) ? '' : '?';
-                        const type = swaggerTypeToTsType(value);
+                        let type = swaggerTypeToTsType(value, schemas);
+                        if (optional === '?')
+                            type = stripNullFromUnion(type);
                         return `${key}${optional}: ${type}`;
                     })
                         .join('; ')} }`;
@@ -226,21 +272,25 @@ function swaggerTypeToTsType(schema, schemas) {
     }
     // 处理 anyOf 或 oneOf
     else if (schema.anyOf || schema.oneOf) {
-        const types = (schema.anyOf || schema.oneOf)
-            .map((s) => {
+        const types = (schema.anyOf || schema.oneOf).map((s) => {
             // 特殊处理 type: 'null'
             if (s.type === 'null')
                 return 'null';
-            return swaggerTypeToTsType(s);
-        })
-            .filter((t) => t !== 'any');
-        // 去重
-        const uniqueTypes = Array.from(new Set(types));
-        if (uniqueTypes.length > 0) {
-            baseType = uniqueTypes.join(' | ');
+            return swaggerTypeToTsType(s, schemas);
+        });
+        // 如果包含 any，则直接返回 any
+        if (types.includes('any')) {
+            baseType = 'any';
         }
         else {
-            baseType = 'any';
+            // 去重
+            const uniqueTypes = Array.from(new Set(types));
+            if (uniqueTypes.length > 0) {
+                baseType = uniqueTypes.join(' | ');
+            }
+            else {
+                baseType = 'any';
+            }
         }
     }
     // 处理引用类型
@@ -248,7 +298,10 @@ function swaggerTypeToTsType(schema, schemas) {
         const refName = schema.$ref.split('/').pop();
         baseType = sanitizeTypeName(refName || 'any');
         // 如果提供了 schemas 上下文,检查被引用的 schema 是否是数组类型
-        if (schemas && refName) {
+        if (schemas &&
+            refName &&
+            typeof schema.$ref === 'string' &&
+            schema.$ref.startsWith('#/')) {
             const referencedSchema = schemas[refName];
             if (referencedSchema && referencedSchema.type === 'array') {
                 // 被引用的 schema 是数组类型,添加 []
@@ -258,8 +311,24 @@ function swaggerTypeToTsType(schema, schemas) {
     }
     // 处理数组类型
     else if (schema.type === 'array') {
-        const itemType = swaggerTypeToTsType(schema.items);
-        baseType = `${itemType}[]`;
+        const itemSchema = schema.items;
+        const itemType = swaggerTypeToTsType(itemSchema, schemas);
+        if (itemSchema?.$ref &&
+            schemas &&
+            typeof itemSchema.$ref === 'string' &&
+            itemSchema.$ref.startsWith('#/')) {
+            const refName = itemSchema.$ref.split('/').pop();
+            const referencedSchema = refName ? schemas[refName] : undefined;
+            if (referencedSchema?.type === 'array') {
+                baseType = itemType;
+            }
+            else {
+                baseType = `${itemType}[]`;
+            }
+        }
+        else {
+            baseType = `${itemType}[]`;
+        }
     }
     // 处理对象类型
     else if (schema.type === 'object') {
@@ -267,7 +336,9 @@ function swaggerTypeToTsType(schema, schemas) {
             const properties = Object.entries(schema.properties)
                 .map(([key, value]) => {
                 const optional = schema.required?.includes(key) ? '' : '?';
-                const type = swaggerTypeToTsType(value);
+                let type = swaggerTypeToTsType(value, schemas);
+                if (optional === '?')
+                    type = stripNullFromUnion(type);
                 return `  ${key}${optional}: ${type};`;
             })
                 .join('\n');
@@ -308,6 +379,10 @@ function swaggerTypeToTsType(schema, schemas) {
     }
     // 处理 nullable 属性
     if (schema.nullable === true) {
+        if (baseType === 'any')
+            return 'any';
+        if (baseType.includes('null'))
+            return baseType;
         return `${baseType} | null`;
     }
     return baseType;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swagger2api-v3",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "description": "A command-line tool for generating TypeScript API interfaces from Swagger (OAS 3.0) documentation",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -23,7 +23,7 @@
     "prebuild": "npm run clean",
     "start": "node dist/cli/index.js",
     "dev": "npm run build && npm start",
-    "lint": "prettier --write",
+    "lint": "prettier --write .",
     "generate": "npm run build && node dist/cli/index.js generate",
     "init": "npm run build && node dist/cli/index.js init",
     "validate": "npm run build && node dist/cli/index.js validate",