swagger2api-v3 1.0.7 → 1.0.8

package/README.md

@@ -1,6 +1,6 @@
 # Swagger2API-v3
 
-一个强大的命令行工具，用于从 Swagger/OpenAPI 文档自动生成 TypeScript 接口代码。
+一个强大的命令行工具，用于从 Swagger(OAS3.0) 文档自动生成 TypeScript 接口代码。
 
 ## ✨ 特性
 
@@ -26,7 +26,7 @@ npm install swagger2api-v3
 ### 1. 初始化配置文件
 
 ```bash
-swagger2api-v3 init
+npx swagger2api-v3 init
 ```
 
 ### 2. 配置文件说明
@@ -64,7 +64,7 @@ export default config;
 ### 3. 生成接口代码
 
 ```bash
-swagger2api-v3 generate
+npx swagger2api-v3 generate
 ```
 
 ## ⚙️ 配置选项
@@ -150,16 +150,16 @@ export const authControllerLoginPost = (data: LoginDto, config?: any) => {
 
 ```bash
 # 初始化配置文件
-swagger2api-v3 init [--force]
+npx swagger2api-v3 init [--force]
 
 # 生成接口代码
-swagger2api-v3 generate [--config <path>]
+npx swagger2api-v3 generate [--config <path>]
 
 # 验证配置文件
-swagger2api-v3 validate [--config <path>]
+npx swagger2api-v3 validate [--config <path>]
 
 # 查看帮助
-swagger2api-v3 --help
+npx swagger2api-v3 --help
 ```
 
 ## 📝 NPM 脚本
@@ -170,7 +170,8 @@ swagger2api-v3 --help
 {
   "scripts": {
     "api:generate": "swagger2api-v3 generate",
-    "api:init": "swagger2api-v3 init"
+    "api:init": "swagger2api-v3 init",
+    "api:validate": "swagger2api-v3 validate"
   }
 }
 ```

package/dist/cli/index.js

@@ -109,43 +109,43 @@ program
             console.warn('⚠️ 无法读取package.json，使用默认CommonJS格式');
         }
     }
-    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',
-  
-  // 按标签分组生成文件
-  groupByTags: true,
-  
-  // 是否覆盖更新，默认为true。为true时会先删除输出目录下的所有文件
-  overwrite: true,
-  
-  // 接口路径公共前缀，默认为空字符串
-  prefix: '',
-  
-  // 代码格式化命令（可选）
-  lint: 'prettier --write',
-  
-  // 生成选项
-  options: {
-    // 是否添加注释
-    addComments: true
-  }
-};
-
-${isESModule ? 'export default config;' : 'module.exports = config;'}
+    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',
+  
+  // 按标签分组生成文件
+  groupByTags: true,
+  
+  // 是否覆盖更新，默认为true。为true时会先删除输出目录下的所有文件
+  overwrite: true,
+  
+  // 接口路径公共前缀，默认为空字符串
+  prefix: '',
+  
+  // 代码格式化命令（可选）
+  lint: 'prettier --write',
+  
+  // 生成选项
+  options: {
+    // 是否添加注释
+    addComments: true
+  }
+};
+
+${isESModule ? 'export default config;' : 'module.exports = config;'}
 `;
     try {
         fs.writeFileSync(configPath, configContent, 'utf-8');

package/dist/utils/index.js

@@ -120,6 +120,7 @@ function swaggerTypeToTsType(schema) {
     if (!schema) {
         return 'any';
     }
+    let baseType;
     // 处理 allOf 类型组合
     if (schema.allOf && schema.allOf.length > 0) {
         // 检查是否为泛型模式：第一个是引用类型，第二个定义了扩展属性
@@ -137,7 +138,7 @@ function swaggerTypeToTsType(schema) {
                 }
                 // 如果只有一个属性，直接作为泛型参数
                 if (propertyTypes.length === 1) {
-                    return `${refName}<${propertyTypes[0]}>`;
+                    baseType = `${refName}<${propertyTypes[0]}>`;
                 }
                 // 如果有多个属性，组合成联合类型或对象类型
                 else if (propertyTypes.length > 1) {
@@ -148,29 +149,36 @@ function swaggerTypeToTsType(schema) {
                         return `${key}${optional}: ${type}`;
                     })
                         .join('; ')} }`;
-                    return `${refName}<${combinedType}>`;
+                    baseType = `${refName}<${combinedType}>`;
                 }
+                else {
+                    baseType = refName || 'any';
+                }
+            }
+            else {
+                baseType = refName || 'any';
             }
-            return refName || 'any';
         }
-        // 如果不是引用，尝试合并所有类型
-        const types = schema.allOf
-            .map((s) => swaggerTypeToTsType(s))
-            .filter((t) => t !== 'any');
-        return types.length > 0 ? types[0] : 'any';
+        else {
+            // 如果不是引用，尝试合并所有类型
+            const types = schema.allOf
+                .map((s) => swaggerTypeToTsType(s))
+                .filter((t) => t !== 'any');
+            baseType = types.length > 0 ? types[0] : 'any';
+        }
     }
     // 处理引用类型
-    if (schema.$ref) {
+    else if (schema.$ref) {
         const refName = schema.$ref.split('/').pop();
-        return refName || 'any';
+        baseType = refName || 'any';
     }
     // 处理数组类型
-    if (schema.type === 'array') {
+    else if (schema.type === 'array') {
         const itemType = swaggerTypeToTsType(schema.items);
-        return `${itemType}[]`;
+        baseType = `${itemType}[]`;
     }
     // 处理对象类型
-    if (schema.type === 'object') {
+    else if (schema.type === 'object') {
         if (schema.properties) {
             const properties = Object.entries(schema.properties)
                 .map(([key, value]) => {
@@ -179,27 +187,43 @@ function swaggerTypeToTsType(schema) {
                 return `  ${key}${optional}: ${type};`;
             })
                 .join('\n');
-            return `{\n${properties}\n}`;
+            baseType = `{\n${properties}\n}`;
+        }
+        else {
+            baseType = 'Record<string, any>';
         }
-        return 'Record<string, any>';
     }
     // 处理基本类型
-    switch (schema.type) {
-        case 'integer':
-        case 'number':
-            return 'number';
-        case 'string':
-            if (schema.enum) {
-                return schema.enum.map((value) => `'${value}'`).join(' | ');
-            }
-            return 'string';
-        case 'boolean':
-            return 'boolean';
-        case 'file':
-            return 'File';
-        default:
-            return 'any';
+    else {
+        switch (schema.type) {
+            case 'integer':
+            case 'number':
+                baseType = 'number';
+                break;
+            case 'string':
+                if (schema.enum) {
+                    baseType = schema.enum.map((value) => `'${value}'`).join(' | ');
+                }
+                else {
+                    baseType = 'string';
+                }
+                break;
+            case 'boolean':
+                baseType = 'boolean';
+                break;
+            case 'file':
+                baseType = 'File';
+                break;
+            default:
+                baseType = 'any';
+                break;
+        }
+    }
+    // 处理 nullable 属性
+    if (schema.nullable === true) {
+        return `${baseType} | null`;
     }
+    return baseType;
 }
 /**
  * 从Swagger参数生成TypeScript参数类型
@@ -315,11 +339,33 @@ function generateApiComment(operation, parameters) {
         comments.push(` * ${operation.description}`);
     }
     if (parameters && parameters.length > 0) {
-        comments.push(' *');
-        parameters.forEach((param) => {
-            const description = param.description || '';
-            comments.push(` * @param ${param.name} ${description}`);
-        });
+        // 收集不同类型的参数
+        const queryParams = parameters.filter((p) => p.in === 'query');
+        const pathParams = parameters.filter((p) => p.in === 'path');
+        const bodyParams = parameters.filter((p) => p.in === 'body');
+        const formParams = parameters.filter((p) => p.in === 'formData');
+        const hasParams = queryParams.length > 0 || pathParams.length > 0;
+        const hasData = bodyParams.length > 0 || formParams.length > 0;
+        if (hasParams || hasData) {
+            comments.push(' *');
+            // 如果有查询参数或路径参数，添加params注释
+            if (hasParams) {
+                const paramDescriptions = [...pathParams, ...queryParams]
+                    .map(p => p.description || '')
+                    .filter(desc => desc)
+                    .join(', ');
+                const description = paramDescriptions || '请求参数';
+                comments.push(` * @param params ${description}`);
+            }
+            // 如果有请求体参数，添加data注释
+            if (hasData) {
+                const dataParam = bodyParams[0] || formParams[0];
+                const description = dataParam?.description || '请求数据';
+                comments.push(` * @param data ${description}`);
+            }
+            // 添加config参数注释
+            comments.push(` * @param config 可选的请求配置`);
+        }
     }
     if (operation.deprecated) {
         comments.push(' * @deprecated');

package/package.json

@@ -1,68 +1,68 @@
-{
-  "name": "swagger2api-v3",
-  "version": "1.0.7",
-  "description": "从 Swagger/OpenAPI 文档生成 TypeScript API 接口的命令行工具",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "type": "commonjs",
-  "bin": {
-    "swagger2api-v3": "dist/cli/index.js"
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "package.json"
-  ],
-  "scripts": {
-    "test": "jest",
-    "test:watch": "jest --watch",
-    "test:coverage": "jest --coverage",
-    "test:ci": "jest --ci --coverage --watchAll=false",
-    "build": "tsc",
-    "clean": "rimraf dist",
-    "prebuild": "npm run clean",
-    "start": "node dist/cli/index.js",
-    "dev": "npm run build && npm start",
-    "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",
-    "swagger:generate": "npm run generate",
-    "swagger:run": "npm run generate",
-    "swagger:init": "npm run init",
-    "swagger:validate": "npm run validate"
-  },
-  "keywords": [
-    "swagger",
-    "openapi",
-    "typescript",
-    "api",
-    "generator",
-    "cli",
-    "code-generation"
-  ],
-  "author": "xiaoyang",
-  "license": "MIT",
-  "homepage": "https://github.com/xiaoyang33/swagger2api-v3#readme",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/xiaoyang33/swagger2api-v3.git"
-  },
-  "bugs": {
-    "url": "https://github.com/xiaoyang33/swagger2api-v3/issues"
-  },
-  "packageManager": "pnpm@10.11.0",
-  "devDependencies": {
-    "@types/jest": "^29.5.0",
-    "@types/node": "^24.3.1",
-    "jest": "^29.5.0",
-    "prettier": "^3.6.2",
-    "rimraf": "^6.0.1",
-    "ts-jest": "^29.1.0",
-    "typescript": "^5.9.2"
-  },
-  "dependencies": {
-    "axios": "^1.11.0",
-    "commander": "^12.0.0"
-  }
-}
+{
+  "name": "swagger2api-v3",
+  "version": "1.0.8",
+  "description": "从 Swagger/OpenAPI 文档生成 TypeScript API 接口的命令行工具",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "commonjs",
+  "bin": {
+    "swagger2api-v3": "dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "package.json"
+  ],
+  "scripts": {
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "test:ci": "jest --ci --coverage --watchAll=false",
+    "build": "tsc",
+    "clean": "rimraf dist",
+    "prebuild": "npm run clean",
+    "start": "node dist/cli/index.js",
+    "dev": "npm run build && npm start",
+    "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",
+    "swagger:generate": "npm run generate",
+    "swagger:run": "npm run generate",
+    "swagger:init": "npm run init",
+    "swagger:validate": "npm run validate"
+  },
+  "keywords": [
+    "swagger",
+    "openapi",
+    "typescript",
+    "api",
+    "generator",
+    "cli",
+    "code-generation"
+  ],
+  "author": "xiaoyang",
+  "license": "MIT",
+  "homepage": "https://github.com/xiaoyang33/swagger2api-v3#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/xiaoyang33/swagger2api-v3.git"
+  },
+  "bugs": {
+    "url": "https://github.com/xiaoyang33/swagger2api-v3/issues"
+  },
+  "packageManager": "pnpm@10.11.0",
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@types/node": "^24.3.1",
+    "jest": "^29.5.0",
+    "prettier": "^3.6.2",
+    "rimraf": "^6.0.1",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.9.2"
+  },
+  "dependencies": {
+    "axios": "^1.11.0",
+    "commander": "^12.0.0"
+  }
+}