swagger2api-v3 1.1.1 → 1.1.2

package/README.md

@@ -1,235 +1,235 @@
-# Swagger2API-v3
-
-English | [中文](./README_CN.md)
-
-A powerful command-line tool for automatically generating TypeScript interface code from Swagger (OAS3.0) documentation.
-
-## ✨ 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. Initialize Configuration File
-
-```bash
-npx swagger2api-v3 init
-```
-
-### 2. Configuration File Description
-
-The tool automatically generates configuration files in the corresponding format based on the project environment:
-
-**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
-  }
-};
-
-module.exports = config;
-```
-
-**ES Module Environment** (`"type": "module"`):
-```javascript
-const config = {
-  // ... same configuration
-};
-
-export default config;
-```
-
-### 3. Generate Interface Code
-
-```bash
-npx swagger2api-v3 generate
-```
-
-## ⚙️ Configuration Options
-
-| 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. Supports `'typescript'` and `'javascript'`. `'javascript'` outputs `.js` files and skips type file generation |
-| `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 |
-| `requestStyle` | 'method' \| 'generic' | `'generic'` | Request call style: `method` uses `request.get/post`, `generic` uses `request({ method })` |
-| `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` |
-| `options.addComments` | boolean | `true` | Whether to add detailed comments |
-
-## 📁 Generated File Structure
-
-### Grouped by Tags (Recommended)
-
-```
-src/api/
-├── types.ts           # Data type definitions (TypeScript mode only)
-├── user/              # User-related APIs
-│   └── index.ts
-├── auth/              # Auth-related APIs
-│   └── index.ts
-└── index.ts          # Entry file
-```
-
-### JavaScript Output
-
-When `generator: 'javascript'` is set:
-
-- Outputs `.js` files (`index.js`, `api.js`, `user/index.js`, etc.)
-- Does not generate a `types.ts` file
-- Removes TypeScript-specific syntax (types, `import type`, generics like `<T>`)
-
-Example generated API function (method style):
-
-```javascript
-export const codeAuth = (data, config) => {
-  return request.post({ url: '/api/auth/codeAuth', data, ...config });
-};
-```
-
-Example generated API function (generic style):
-
-```javascript
-export const codeAuth = (data, config) => {
-  return request({ url: '/api/auth/codeAuth', method: 'POST', data, ...config });
-};
-```
-
-### Not Grouped
-
-```
-src/api/
-├── 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 {
-  /** User ID */
-  id: string;
-  /** Username */
-  username: string;
-}
-```
-
-### Generated API Interfaces
-
-```typescript
-// authController/index.ts
-import { request } from '@/utils/request';
-import type { LoginDto, LoginRespDto } from '../types';
-
-/**
- * Login
- * @param data Login parameters
- * @param config Optional request configuration
- */
-export const authControllerLoginPost = (data: LoginDto, config?: any) => {
-  return request.post<LoginRespDto>({
-    url: '/admin/auth/login',
-    data,
-    ...config
-  });
-};
-
-// When requestStyle is set to 'generic':
-export const authControllerLoginPost2 = (data: LoginDto, config?: any) => {
-  return request<LoginRespDto>({
-    url: '/admin/auth/login',
-    data,
-    method: 'POST',
-    ...config
-  });
-};
-```
-
-## 🔧 CLI Commands
-
-```bash
-# Initialize configuration file
-npx swagger2api-v3 init [--force]
-
-# Generate interface code
-npx swagger2api-v3 generate [--config <path>]
-
-# Validate configuration file
-npx swagger2api-v3 validate [--config <path>]
-
-# Show help
-npx swagger2api-v3 --help
-```
-
-## 📝 NPM Scripts
-
-Add to `package.json`:
-
-```json
-{
-  "scripts": {
-    "api:generate": "swagger2api-v3 generate",
-    "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 = {
-  // ... other configurations
-  lint: 'prettier --write'  // or 'eslint --fix', etc.
-};
-```
-
-## 🤝 Contributing
-
-Issues and Pull Requests are welcome!
-
-## 📄 License
-
+# Swagger2API-v3
+
+English | [中文](./README_CN.md)
+
+A powerful command-line tool for automatically generating TypeScript interface code from Swagger (OAS3.0) documentation.
+
+## ✨ 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. Initialize Configuration File
+
+```bash
+npx swagger2api-v3 init
+```
+
+### 2. Configuration File Description
+
+The tool automatically generates configuration files in the corresponding format based on the project environment:
+
+**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
+  }
+};
+
+module.exports = config;
+```
+
+**ES Module Environment** (`"type": "module"`):
+```javascript
+const config = {
+  // ... same configuration
+};
+
+export default config;
+```
+
+### 3. Generate Interface Code
+
+```bash
+npx swagger2api-v3 generate
+```
+
+## ⚙️ Configuration Options
+
+| 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. Supports `'typescript'` and `'javascript'`. `'javascript'` outputs `.js` files and skips type file generation |
+| `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 |
+| `requestStyle` | 'method' \| 'generic' | `'generic'` | Request call style: `method` uses `request.get/post`, `generic` uses `request({ method })` |
+| `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` |
+| `options.addComments` | boolean | `true` | Whether to add detailed comments |
+
+## 📁 Generated File Structure
+
+### Grouped by Tags (Recommended)
+
+```
+src/api/
+├── types.ts           # Data type definitions (TypeScript mode only)
+├── user/              # User-related APIs
+│   └── index.ts
+├── auth/              # Auth-related APIs
+│   └── index.ts
+└── index.ts          # Entry file
+```
+
+### JavaScript Output
+
+When `generator: 'javascript'` is set:
+
+- Outputs `.js` files (`index.js`, `api.js`, `user/index.js`, etc.)
+- Does not generate a `types.ts` file
+- Removes TypeScript-specific syntax (types, `import type`, generics like `<T>`)
+
+Example generated API function (method style):
+
+```javascript
+export const codeAuth = (data, config) => {
+  return request.post({ url: '/api/auth/codeAuth', data, ...config });
+};
+```
+
+Example generated API function (generic style):
+
+```javascript
+export const codeAuth = (data, config) => {
+  return request({ url: '/api/auth/codeAuth', method: 'POST', data, ...config });
+};
+```
+
+### Not Grouped
+
+```
+src/api/
+├── 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 {
+  /** User ID */
+  id: string;
+  /** Username */
+  username: string;
+}
+```
+
+### Generated API Interfaces
+
+```typescript
+// authController/index.ts
+import { request } from '@/utils/request';
+import type { LoginDto, LoginRespDto } from '../types';
+
+/**
+ * Login
+ * @param data Login parameters
+ * @param config Optional request configuration
+ */
+export const authControllerLoginPost = (data: LoginDto, config?: any) => {
+  return request.post<LoginRespDto>({
+    url: '/admin/auth/login',
+    data,
+    ...config
+  });
+};
+
+// When requestStyle is set to 'generic':
+export const authControllerLoginPost2 = (data: LoginDto, config?: any) => {
+  return request<LoginRespDto>({
+    url: '/admin/auth/login',
+    data,
+    method: 'POST',
+    ...config
+  });
+};
+```
+
+## 🔧 CLI Commands
+
+```bash
+# Initialize configuration file
+npx swagger2api-v3 init [--force]
+
+# Generate interface code
+npx swagger2api-v3 generate [--config <path>]
+
+# Validate configuration file
+npx swagger2api-v3 validate [--config <path>]
+
+# Show help
+npx swagger2api-v3 --help
+```
+
+## 📝 NPM Scripts
+
+Add to `package.json`:
+
+```json
+{
+  "scripts": {
+    "api:generate": "swagger2api-v3 generate",
+    "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 = {
+  // ... other configurations
+  lint: 'prettier --write'  // or 'eslint --fix', etc.
+};
+```
+
+## 🤝 Contributing
+
+Issues and Pull Requests are welcome!
+
+## 📄 License
+
 MIT License

package/dist/cli/index.js

@@ -110,51 +110,51 @@ program
             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: [],
-  
-  // 生成选项
-  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', // 可选 '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: [],
+  
+  // 生成选项
+  options: {
+    // 是否添加注释
+    addComments: true
+  }
+};
+
+${isESModule ? 'export default config;' : 'module.exports = config;'}
 `;
     try {
         fs.writeFileSync(configPath, configContent, 'utf-8');

package/dist/core/generator.d.ts

@@ -64,6 +64,7 @@ export declare class CodeGenerator {
     /**
      * 收集API数组中实际使用的类型
      * @param apis API接口数组
+     * @param definedTypes 已定义的类型数组
      * @returns 使用的类型名称数组
      */
     private collectUsedTypes;

package/dist/core/generator.js

@@ -166,7 +166,7 @@ class CodeGenerator {
             importTemplate + ';'
         ];
         // 收集当前文件实际使用的类型
-        const usedTypes = this.collectUsedTypes(apis);
+        const usedTypes = this.collectUsedTypes(apis, types); // 传入 types
         // 添加类型导入（仅在 TypeScript 且生成类型文件时）
         if (this.config.generator === 'typescript' &&
             this.config.options?.generateModels !== false &&
@@ -307,9 +307,10 @@ class CodeGenerator {
     /**
      * 收集API数组中实际使用的类型
      * @param apis API接口数组
+     * @param definedTypes 已定义的类型数组
      * @returns 使用的类型名称数组
      */
-    collectUsedTypes(apis) {
+    collectUsedTypes(apis, definedTypes) {
         const usedTypes = new Set();
         apis.forEach((api) => {
             // 收集响应类型
@@ -334,6 +335,13 @@ class CodeGenerator {
                 }
             });
         });
+        // 如果提供了 definedTypes，则只保留已定义的类型
+        if (definedTypes) {
+            const definedTypeNames = new Set(definedTypes.map((t) => t.name));
+            return Array.from(usedTypes)
+                .filter((name) => definedTypeNames.has(name))
+                .sort();
+        }
         return Array.from(usedTypes).sort();
     }
     /**

package/dist/core/parser.js

@@ -116,6 +116,16 @@ class SwaggerParser {
      */
     parseTypes() {
         const types = [];
+        // Debug log
+        console.log('解析类型定义...');
+        console.log('Has definitions:', !!this.document.definitions);
+        console.log('Has components:', !!this.document.components);
+        if (this.document.components) {
+            console.log('Has schemas:', !!this.document.components.schemas);
+            if (this.document.components.schemas) {
+                console.log('Schema keys:', Object.keys(this.document.components.schemas));
+            }
+        }
         // 解析 Swagger 2.0 definitions
         if (this.document.definitions) {
             for (const [name, schema] of Object.entries(this.document.definitions)) {

package/dist/utils/index.js

@@ -339,9 +339,15 @@ function removeDirectory(dirPath) {
 async function loadSwaggerDocument(input) {
     try {
         if (input.startsWith('http://') || input.startsWith('https://')) {
-            // 从URL加载
-            const response = await axios_1.default.get(input);
-            return response.data;
+            const { data } = await axios_1.default.get(input);
+            console.log('Loaded from URL:', input);
+            if (data.components?.schemas) {
+                console.log('Schemas count:', Object.keys(data.components.schemas).length);
+            }
+            else {
+                console.log('No schemas in loaded data');
+            }
+            return data;
         }
         else {
             // 从文件加载
@@ -390,8 +396,8 @@ function generateApiComment(operation, parameters) {
             // 如果有查询参数或路径参数，添加params注释
             if (hasParams) {
                 const paramDescriptions = [...pathParams, ...queryParams]
-                    .map(p => p.description || '')
-                    .filter(desc => desc)
+                    .map((p) => p.description || '')
+                    .filter((desc) => desc)
                     .join(', ');
                 const description = paramDescriptions || '请求参数';
                 comments.push(` * @param params ${description}`);
@@ -426,6 +432,9 @@ function sanitizeFilename(filename) {
  * @returns TypeScript类型字符串
  */
 function getResponseType(responses) {
+    if (!responses) {
+        return 'any';
+    }
     // 优先获取200响应
     const successResponse = responses['200'] || responses['201'] || responses['default'];
     if (!successResponse) {

package/package.json

@@ -1,68 +1,68 @@
-{
-  "name": "swagger2api-v3",
-  "version": "1.1.1",
-  "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",
-  "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.1.2",
+  "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",
+  "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"
+  }
+}