swagger2api-v3 1.0.7 → 1.0.9

package/README.md

@@ -1,39 +1,41 @@
 # Swagger2API-v3
 
-一个强大的命令行工具，用于从 Swagger/OpenAPI 文档自动生成 TypeScript 接口代码。
+English | [中文](./README_CN.md)
 
-## ✨ 特性
+A powerful command-line tool for automatically generating TypeScript interface code from Swagger (OAS3.0) documentation.
 
-- 🚀 **快速生成** - 从 Swagger JSON 快速生成 TypeScript 接口代码
-- 📁 **智能分组** - 支持按 Swagger 标签自动分组生成文件
-- 📝 **详细注释** - 自动生成包含描述、参数、返回值的详细注释
-- 🎨 **代码格式化** - 支持自定义格式化命令
-- ⚙️ **环境适配** - 自动检测项目环境，生成对应格式的配置文件
-- 🔧 **CLI 工具** - 提供完整的命令行工具
+## ✨ Features
 
-## 📦 安装
+- 🚀 **Fast Generation** - Quickly generate TypeScript interface code from Swagger JSON
+- 📁 **Smart Grouping** - Support automatic file grouping by Swagger tags
+- 📝 **Detailed Comments** - Automatically generate detailed comments including descriptions, parameters, and return values
+- 🎨 **Code Formatting** - Support custom formatting commands
+- ⚙️ **Environment Adaptation** - Automatically detect project environment and generate corresponding configuration files
+- 🔧 **CLI Tool** - Provide complete command-line tools
+
+## 📦 Installation
 
 ```bash
-# 全局安装
+# Global installation
 npm install -g swagger2api-v3
 
-# 项目依赖
+# Project dependency
 npm install swagger2api-v3
 ```
 
-## 🚀 快速开始
+## 🚀 Quick Start
 
-### 1. 初始化配置文件
+### 1. Initialize Configuration File
 
 ```bash
-swagger2api-v3 init
+npx swagger2api-v3 init
 ```
 
-### 2. 配置文件说明
+### 2. Configuration File Description
 
-工具会根据项目环境自动生成对应格式的配置文件：
+The tool automatically generates configuration files in the corresponding format based on the project environment:
 
-**CommonJS 环境** (`"type": "commonjs"` 或未设置)：
+**CommonJS Environment** (`"type": "commonjs"` or not set):
 ```javascript
 const config = {
   input: 'https://petstore.swagger.io/v2/swagger.json',
@@ -52,80 +54,80 @@ const config = {
 module.exports = config;
 ```
 
-**ES 模块环境** (`"type": "module"`)：
+**ES Module Environment** (`"type": "module"`):
 ```javascript
 const config = {
-  // ... 相同配置
+  // ... same configuration
 };
 
 export default config;
 ```
 
-### 3. 生成接口代码
+### 3. Generate Interface Code
 
 ```bash
-swagger2api-v3 generate
+npx swagger2api-v3 generate
 ```
 
-## ⚙️ 配置选项
+## ⚙️ Configuration Options
 
-| 选项 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `input` | string | - | Swagger JSON 文件路径或 URL |
-| `output` | string | `'./src/api'` | 生成代码的输出目录 |
-| `generator` | string | `'typescript'` | 代码生成器类型 |
-| `groupByTags` | boolean | `true` | 是否按标签分组生成文件 |
-| `overwrite` | boolean | `true` | 是否覆盖已存在的文件 |
-| `prefix` | string | `''` | 接口路径公共前缀 |
-| `importTemplate` | string | - | request 函数导入语句模板 |
-| `lint` | string | - | 代码格式化命令（可选） |
-| `options.addComments` | boolean | `true` | 是否添加详细注释 |
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `input` | string | - | Swagger JSON file path or URL |
+| `output` | string | `'./src/api'` | Output directory for generated code |
+| `generator` | string | `'typescript'` | Code generator type |
+| `groupByTags` | boolean | `true` | Whether to group files by tags |
+| `overwrite` | boolean | `true` | Whether to overwrite existing files |
+| `prefix` | string | `''` | Common prefix for API paths |
+| `importTemplate` | string | - | Import statement template for request function |
+| `lint` | string | - | Code formatting command (optional) |
+| `options.addComments` | boolean | `true` | Whether to add detailed comments |
 
-## 📁 生成的文件结构
+## 📁 Generated File Structure
 
-### 按标签分组 (推荐)
+### Grouped by Tags (Recommended)
 
 ```
 src/api/
-├── types.ts           # 数据类型定义
-├── user/              # User 相关接口
+├── types.ts           # Data type definitions
+├── user/              # User-related APIs
 │   └── index.ts
-├── auth/              # Auth 相关接口
+├── auth/              # Auth-related APIs
 │   └── index.ts
-└── index.ts          # 入口文件
+└── index.ts          # Entry file
 ```
 
-### 不分组
+### Not Grouped
 
 ```
 src/api/
-├── types.ts       # 数据类型定义
-├── api.ts         # 所有 API 接口
-└── index.ts       # 入口文件
+├── types.ts       # Data type definitions
+├── api.ts         # All API interfaces
+└── index.ts       # Entry file
 ```
 
-## 💡 使用示例
+## 💡 Usage Examples
 
-### 生成的类型定义
+### Generated Type Definitions
 
 ```typescript
 // types.ts
 export interface LoginDto {
-  /** 账号 */
+  /** Account */
   account: string;
-  /** 密码 */
+  /** Password */
   password: string;
 }
 
 export interface UserInfo {
-  /** 用户ID */
+  /** User ID */
   id: string;
-  /** 用户名 */
+  /** Username */
   username: string;
 }
 ```
 
-### 生成的 API 接口
+### Generated API Interfaces
 
 ```typescript
 // authController/index.ts
@@ -133,9 +135,9 @@ import { request } from '@/utils/request';
 import type { LoginDto, LoginRespDto } from '../types';
 
 /**
- * 登录
- * @param data 登录参数
- * @param config 可选的请求配置
+ * Login
+ * @param data Login parameters
+ * @param config Optional request configuration
  */
 export const authControllerLoginPost = (data: LoginDto, config?: any) => {
   return request.post<LoginRespDto>({
@@ -146,51 +148,52 @@ export const authControllerLoginPost = (data: LoginDto, config?: any) => {
 };
 ```
 
-## 🔧 CLI 命令
+## 🔧 CLI Commands
 
 ```bash
-# 初始化配置文件
-swagger2api-v3 init [--force]
+# Initialize configuration file
+npx swagger2api-v3 init [--force]
 
-# 生成接口代码
-swagger2api-v3 generate [--config <path>]
+# Generate interface code
+npx swagger2api-v3 generate [--config <path>]
 
-# 验证配置文件
-swagger2api-v3 validate [--config <path>]
+# Validate configuration file
+npx swagger2api-v3 validate [--config <path>]
 
-# 查看帮助
-swagger2api-v3 --help
+# Show help
+npx swagger2api-v3 --help
 ```
 
-## 📝 NPM 脚本
+## 📝 NPM Scripts
 
-在 `package.json` 中添加：
+Add to `package.json`:
 
 ```json
 {
   "scripts": {
     "api:generate": "swagger2api-v3 generate",
-    "api:init": "swagger2api-v3 init"
+    "api:init": "swagger2api-v3 init",
+    "api:validate": "swagger2api-v3 validate"
   }
 }
 ```
 
-## 🎨 代码格式化
+## 🎨 Code Formatting
 
-支持在生成完成后自动执行格式化命令：
+Support automatic execution of formatting commands after generation:
 
 ```javascript
-// 配置文件中
+// In configuration file
 const config = {
-  // ... 其他配置
-  lint: 'prettier --write'  // 或 'eslint --fix' 等
+  // ... other configurations
+  lint: 'prettier --write'  // or 'eslint --fix', etc.
 };
 ```
 
-## 🤝 贡献
+## 🤝 Contributing
 
-欢迎提交 Issue 和 Pull Request！
+Issues and Pull Requests are welcome!
 
-## 📄 许可证
+## 📄 License
 
 MIT License

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.9",
+  "description": "从 Swagger(OAS3.0) 文档生成 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"
+  }
+}