swagger2api-v3 1.0.9 → 1.0.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +198 -198
  2. package/dist/cli/index.js +41 -40
  3. package/package.json +68 -68
package/README.md CHANGED
@@ -1,199 +1,199 @@
1
- # Swagger2API-v3
2
-
3
- English | [中文](./README_CN.md)
4
-
5
- A powerful command-line tool for automatically generating TypeScript interface code from Swagger (OAS3.0) documentation.
6
-
7
- ## ✨ Features
8
-
9
- - 🚀 **Fast Generation** - Quickly generate TypeScript interface code from Swagger JSON
10
- - 📁 **Smart Grouping** - Support automatic file grouping by Swagger tags
11
- - 📝 **Detailed Comments** - Automatically generate detailed comments including descriptions, parameters, and return values
12
- - 🎨 **Code Formatting** - Support custom formatting commands
13
- - ⚙️ **Environment Adaptation** - Automatically detect project environment and generate corresponding configuration files
14
- - 🔧 **CLI Tool** - Provide complete command-line tools
15
-
16
- ## 📦 Installation
17
-
18
- ```bash
19
- # Global installation
20
- npm install -g swagger2api-v3
21
-
22
- # Project dependency
23
- npm install swagger2api-v3
24
- ```
25
-
26
- ## 🚀 Quick Start
27
-
28
- ### 1. Initialize Configuration File
29
-
30
- ```bash
31
- npx swagger2api-v3 init
32
- ```
33
-
34
- ### 2. Configuration File Description
35
-
36
- The tool automatically generates configuration files in the corresponding format based on the project environment:
37
-
38
- **CommonJS Environment** (`"type": "commonjs"` or not set):
39
- ```javascript
40
- const config = {
41
- input: 'https://petstore.swagger.io/v2/swagger.json',
42
- output: './src/api',
43
- importTemplate: "import { request } from '@/utils/request';",
44
- generator: 'typescript',
45
- groupByTags: true,
46
- overwrite: true,
47
- prefix: '',
48
- lint: 'prettier --write',
49
- options: {
50
- addComments: true
51
- }
52
- };
53
-
54
- module.exports = config;
55
- ```
56
-
57
- **ES Module Environment** (`"type": "module"`):
58
- ```javascript
59
- const config = {
60
- // ... same configuration
61
- };
62
-
63
- export default config;
64
- ```
65
-
66
- ### 3. Generate Interface Code
67
-
68
- ```bash
69
- npx swagger2api-v3 generate
70
- ```
71
-
72
- ## ⚙️ Configuration Options
73
-
74
- | Option | Type | Default | Description |
75
- |--------|------|---------|-------------|
76
- | `input` | string | - | Swagger JSON file path or URL |
77
- | `output` | string | `'./src/api'` | Output directory for generated code |
78
- | `generator` | string | `'typescript'` | Code generator type |
79
- | `groupByTags` | boolean | `true` | Whether to group files by tags |
80
- | `overwrite` | boolean | `true` | Whether to overwrite existing files |
81
- | `prefix` | string | `''` | Common prefix for API paths |
82
- | `importTemplate` | string | - | Import statement template for request function |
83
- | `lint` | string | - | Code formatting command (optional) |
84
- | `options.addComments` | boolean | `true` | Whether to add detailed comments |
85
-
86
- ## 📁 Generated File Structure
87
-
88
- ### Grouped by Tags (Recommended)
89
-
90
- ```
91
- src/api/
92
- ├── types.ts # Data type definitions
93
- ├── user/ # User-related APIs
94
- │ └── index.ts
95
- ├── auth/ # Auth-related APIs
96
- │ └── index.ts
97
- └── index.ts # Entry file
98
- ```
99
-
100
- ### Not Grouped
101
-
102
- ```
103
- src/api/
104
- ├── types.ts # Data type definitions
105
- ├── api.ts # All API interfaces
106
- └── index.ts # Entry file
107
- ```
108
-
109
- ## 💡 Usage Examples
110
-
111
- ### Generated Type Definitions
112
-
113
- ```typescript
114
- // types.ts
115
- export interface LoginDto {
116
- /** Account */
117
- account: string;
118
- /** Password */
119
- password: string;
120
- }
121
-
122
- export interface UserInfo {
123
- /** User ID */
124
- id: string;
125
- /** Username */
126
- username: string;
127
- }
128
- ```
129
-
130
- ### Generated API Interfaces
131
-
132
- ```typescript
133
- // authController/index.ts
134
- import { request } from '@/utils/request';
135
- import type { LoginDto, LoginRespDto } from '../types';
136
-
137
- /**
138
- * Login
139
- * @param data Login parameters
140
- * @param config Optional request configuration
141
- */
142
- export const authControllerLoginPost = (data: LoginDto, config?: any) => {
143
- return request.post<LoginRespDto>({
144
- url: '/admin/auth/login',
145
- data,
146
- ...config
147
- });
148
- };
149
- ```
150
-
151
- ## 🔧 CLI Commands
152
-
153
- ```bash
154
- # Initialize configuration file
155
- npx swagger2api-v3 init [--force]
156
-
157
- # Generate interface code
158
- npx swagger2api-v3 generate [--config <path>]
159
-
160
- # Validate configuration file
161
- npx swagger2api-v3 validate [--config <path>]
162
-
163
- # Show help
164
- npx swagger2api-v3 --help
165
- ```
166
-
167
- ## 📝 NPM Scripts
168
-
169
- Add to `package.json`:
170
-
171
- ```json
172
- {
173
- "scripts": {
174
- "api:generate": "swagger2api-v3 generate",
175
- "api:init": "swagger2api-v3 init",
176
- "api:validate": "swagger2api-v3 validate"
177
- }
178
- }
179
- ```
180
-
181
- ## 🎨 Code Formatting
182
-
183
- Support automatic execution of formatting commands after generation:
184
-
185
- ```javascript
186
- // In configuration file
187
- const config = {
188
- // ... other configurations
189
- lint: 'prettier --write' // or 'eslint --fix', etc.
190
- };
191
- ```
192
-
193
- ## 🤝 Contributing
194
-
195
- Issues and Pull Requests are welcome!
196
-
197
- ## 📄 License
198
-
1
+ # Swagger2API-v3
2
+
3
+ English | [中文](./README_CN.md)
4
+
5
+ A powerful command-line tool for automatically generating TypeScript interface code from Swagger (OAS3.0) documentation.
6
+
7
+ ## ✨ Features
8
+
9
+ - 🚀 **Fast Generation** - Quickly generate TypeScript interface code from Swagger JSON
10
+ - 📁 **Smart Grouping** - Support automatic file grouping by Swagger tags
11
+ - 📝 **Detailed Comments** - Automatically generate detailed comments including descriptions, parameters, and return values
12
+ - 🎨 **Code Formatting** - Support custom formatting commands
13
+ - ⚙️ **Environment Adaptation** - Automatically detect project environment and generate corresponding configuration files
14
+ - 🔧 **CLI Tool** - Provide complete command-line tools
15
+
16
+ ## 📦 Installation
17
+
18
+ ```bash
19
+ # Global installation
20
+ npm install -g swagger2api-v3
21
+
22
+ # Project dependency
23
+ npm install swagger2api-v3
24
+ ```
25
+
26
+ ## 🚀 Quick Start
27
+
28
+ ### 1. Initialize Configuration File
29
+
30
+ ```bash
31
+ npx swagger2api-v3 init
32
+ ```
33
+
34
+ ### 2. Configuration File Description
35
+
36
+ The tool automatically generates configuration files in the corresponding format based on the project environment:
37
+
38
+ **CommonJS Environment** (`"type": "commonjs"` or not set):
39
+ ```javascript
40
+ const config = {
41
+ input: 'https://petstore.swagger.io/v2/swagger.json',
42
+ output: './src/api',
43
+ importTemplate: "import { request } from '@/utils/request';",
44
+ generator: 'typescript',
45
+ groupByTags: true,
46
+ overwrite: true,
47
+ prefix: '',
48
+ lint: 'prettier --write',
49
+ options: {
50
+ addComments: true
51
+ }
52
+ };
53
+
54
+ module.exports = config;
55
+ ```
56
+
57
+ **ES Module Environment** (`"type": "module"`):
58
+ ```javascript
59
+ const config = {
60
+ // ... same configuration
61
+ };
62
+
63
+ export default config;
64
+ ```
65
+
66
+ ### 3. Generate Interface Code
67
+
68
+ ```bash
69
+ npx swagger2api-v3 generate
70
+ ```
71
+
72
+ ## ⚙️ Configuration Options
73
+
74
+ | Option | Type | Default | Description |
75
+ |--------|------|---------|-------------|
76
+ | `input` | string | - | Swagger JSON file path or URL |
77
+ | `output` | string | `'./src/api'` | Output directory for generated code |
78
+ | `generator` | string | `'typescript'` | Code generator type |
79
+ | `groupByTags` | boolean | `true` | Whether to group files by tags |
80
+ | `overwrite` | boolean | `true` | Whether to overwrite existing files |
81
+ | `prefix` | string | `''` | Common prefix for API paths |
82
+ | `importTemplate` | string | - | Import statement template for request function |
83
+ | `lint` | string | - | Code formatting command (optional) |
84
+ | `options.addComments` | boolean | `true` | Whether to add detailed comments |
85
+
86
+ ## 📁 Generated File Structure
87
+
88
+ ### Grouped by Tags (Recommended)
89
+
90
+ ```
91
+ src/api/
92
+ ├── types.ts # Data type definitions
93
+ ├── user/ # User-related APIs
94
+ │ └── index.ts
95
+ ├── auth/ # Auth-related APIs
96
+ │ └── index.ts
97
+ └── index.ts # Entry file
98
+ ```
99
+
100
+ ### Not Grouped
101
+
102
+ ```
103
+ src/api/
104
+ ├── types.ts # Data type definitions
105
+ ├── api.ts # All API interfaces
106
+ └── index.ts # Entry file
107
+ ```
108
+
109
+ ## 💡 Usage Examples
110
+
111
+ ### Generated Type Definitions
112
+
113
+ ```typescript
114
+ // types.ts
115
+ export interface LoginDto {
116
+ /** Account */
117
+ account: string;
118
+ /** Password */
119
+ password: string;
120
+ }
121
+
122
+ export interface UserInfo {
123
+ /** User ID */
124
+ id: string;
125
+ /** Username */
126
+ username: string;
127
+ }
128
+ ```
129
+
130
+ ### Generated API Interfaces
131
+
132
+ ```typescript
133
+ // authController/index.ts
134
+ import { request } from '@/utils/request';
135
+ import type { LoginDto, LoginRespDto } from '../types';
136
+
137
+ /**
138
+ * Login
139
+ * @param data Login parameters
140
+ * @param config Optional request configuration
141
+ */
142
+ export const authControllerLoginPost = (data: LoginDto, config?: any) => {
143
+ return request.post<LoginRespDto>({
144
+ url: '/admin/auth/login',
145
+ data,
146
+ ...config
147
+ });
148
+ };
149
+ ```
150
+
151
+ ## 🔧 CLI Commands
152
+
153
+ ```bash
154
+ # Initialize configuration file
155
+ npx swagger2api-v3 init [--force]
156
+
157
+ # Generate interface code
158
+ npx swagger2api-v3 generate [--config <path>]
159
+
160
+ # Validate configuration file
161
+ npx swagger2api-v3 validate [--config <path>]
162
+
163
+ # Show help
164
+ npx swagger2api-v3 --help
165
+ ```
166
+
167
+ ## 📝 NPM Scripts
168
+
169
+ Add to `package.json`:
170
+
171
+ ```json
172
+ {
173
+ "scripts": {
174
+ "api:generate": "swagger2api-v3 generate",
175
+ "api:init": "swagger2api-v3 init",
176
+ "api:validate": "swagger2api-v3 validate"
177
+ }
178
+ }
179
+ ```
180
+
181
+ ## 🎨 Code Formatting
182
+
183
+ Support automatic execution of formatting commands after generation:
184
+
185
+ ```javascript
186
+ // In configuration file
187
+ const config = {
188
+ // ... other configurations
189
+ lint: 'prettier --write' // or 'eslint --fix', etc.
190
+ };
191
+ ```
192
+
193
+ ## 🤝 Contributing
194
+
195
+ Issues and Pull Requests are welcome!
196
+
197
+ ## 📄 License
198
+
199
199
  MIT License
package/dist/cli/index.js CHANGED
@@ -98,54 +98,55 @@ program
98
98
  process.exit(1);
99
99
  }
100
100
  // 检测当前项目的模块类型
101
- let isESModule = false;
101
+ let isESModule = true; // 默认使用 ES Module
102
102
  const packageJsonPath = path.resolve(process.cwd(), 'package.json');
103
103
  if (fs.existsSync(packageJsonPath)) {
104
104
  try {
105
105
  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
106
- isESModule = packageJson.type === 'module';
106
+ // 只有明确设置为 commonjs 时才使用 CommonJS，否则默认使用 ES Module
107
+ isESModule = packageJson.type !== 'commonjs';
107
108
  }
108
109
  catch (error) {
109
- console.warn('⚠️ 无法读取package.json，使用默认CommonJS格式');
110
+ console.warn('⚠️ 无法读取package.json，使用默认ES Module格式');
110
111
  }
111
112
  }
112
- const configContent = `/**
113
- * Swagger2API 配置文件
114
- * 用于配置从 Swagger JSON 生成前端接口的参数
115
- */
116
- const config = {
117
- // Swagger JSON 文件路径或 URL
118
- input: 'http://localhost:3000/admin/docs/json',
119
-
120
- // 输出目录
121
- output: './src/api',
122
-
123
- // request 导入路径模板
124
- importTemplate: "import { request } from '@/utils/request';",
125
-
126
- // 生成器类型
127
- generator: 'typescript',
128
-
129
- // 按标签分组生成文件
130
- groupByTags: true,
131
-
132
- // 是否覆盖更新，默认为true。为true时会先删除输出目录下的所有文件
133
- overwrite: true,
134
-
135
- // 接口路径公共前缀，默认为空字符串
136
- prefix: '',
137
-
138
- // 代码格式化命令（可选）
139
- lint: 'prettier --write',
140
-
141
- // 生成选项
142
- options: {
143
- // 是否添加注释
144
- addComments: true
145
- }
146
- };
147
-
148
- ${isESModule ? 'export default config;' : 'module.exports = config;'}
113
+ const configContent = `/**
114
+ * Swagger2API 配置文件
115
+ * 用于配置从 Swagger JSON 生成前端接口的参数
116
+ */
117
+ const config = {
118
+ // Swagger JSON 文件路径或 URL
119
+ input: 'http://localhost:3000/admin/docs/json',
120
+
121
+ // 输出目录
122
+ output: './src/api',
123
+
124
+ // request 导入路径模板
125
+ importTemplate: "import { request } from '@/utils/request';",
126
+
127
+ // 生成器类型
128
+ generator: 'typescript',
129
+
130
+ // 按标签分组生成文件
131
+ groupByTags: true,
132
+
133
+ // 是否覆盖更新，默认为true。为true时会先删除输出目录下的所有文件
134
+ overwrite: true,
135
+
136
+ // 接口路径公共前缀，默认为空字符串
137
+ prefix: '',
138
+
139
+ // 代码格式化命令（可选）
140
+ lint: 'prettier --write',
141
+
142
+ // 生成选项
143
+ options: {
144
+ // 是否添加注释
145
+ addComments: true
146
+ }
147
+ };
148
+
149
+ ${isESModule ? 'export default config;' : 'module.exports = config;'}
149
150
  `;
150
151
  try {
151
152
  fs.writeFileSync(configPath, configContent, 'utf-8');
package/package.json CHANGED
@@ -1,68 +1,68 @@
1
- {
2
- "name": "swagger2api-v3",
3
- "version": "1.0.9",
4
- "description": "从 Swagger(OAS3.0) 文档生成 TypeScript API 接口的命令行工具",
5
- "main": "dist/index.js",
6
- "types": "dist/index.d.ts",
7
- "type": "commonjs",
8
- "bin": {
9
- "swagger2api-v3": "dist/cli/index.js"
10
- },
11
- "files": [
12
- "dist",
13
- "README.md",
14
- "package.json"
15
- ],
16
- "scripts": {
17
- "test": "jest",
18
- "test:watch": "jest --watch",
19
- "test:coverage": "jest --coverage",
20
- "test:ci": "jest --ci --coverage --watchAll=false",
21
- "build": "tsc",
22
- "clean": "rimraf dist",
23
- "prebuild": "npm run clean",
24
- "start": "node dist/cli/index.js",
25
- "dev": "npm run build && npm start",
26
- "lint": "prettier --write",
27
- "generate": "npm run build && node dist/cli/index.js generate",
28
- "init": "npm run build && node dist/cli/index.js init",
29
- "validate": "npm run build && node dist/cli/index.js validate",
30
- "swagger:generate": "npm run generate",
31
- "swagger:run": "npm run generate",
32
- "swagger:init": "npm run init",
33
- "swagger:validate": "npm run validate"
34
- },
35
- "keywords": [
36
- "swagger",
37
- "openapi",
38
- "typescript",
39
- "api",
40
- "generator",
41
- "cli",
42
- "code-generation"
43
- ],
44
- "author": "xiaoyang",
45
- "license": "MIT",
46
- "homepage": "https://github.com/xiaoyang33/swagger2api-v3#readme",
47
- "repository": {
48
- "type": "git",
49
- "url": "https://github.com/xiaoyang33/swagger2api-v3.git"
50
- },
51
- "bugs": {
52
- "url": "https://github.com/xiaoyang33/swagger2api-v3/issues"
53
- },
54
- "packageManager": "pnpm@10.11.0",
55
- "devDependencies": {
56
- "@types/jest": "^29.5.0",
57
- "@types/node": "^24.3.1",
58
- "jest": "^29.5.0",
59
- "prettier": "^3.6.2",
60
- "rimraf": "^6.0.1",
61
- "ts-jest": "^29.1.0",
62
- "typescript": "^5.9.2"
63
- },
64
- "dependencies": {
65
- "axios": "^1.11.0",
66
- "commander": "^12.0.0"
67
- }
68
- }
1
+ {
2
+ "name": "swagger2api-v3",
3
+ "version": "1.0.10",
4
+ "description": "从 Swagger(OAS3.0) 文档生成 TypeScript API 接口的命令行工具",
5
+ "main": "dist/index.js",
6
+ "types": "dist/index.d.ts",
7
+ "type": "commonjs",
8
+ "bin": {
9
+ "swagger2api-v3": "dist/cli/index.js"
10
+ },
11
+ "files": [
12
+ "dist",
13
+ "README.md",
14
+ "package.json"
15
+ ],
16
+ "scripts": {
17
+ "test": "jest",
18
+ "test:watch": "jest --watch",
19
+ "test:coverage": "jest --coverage",
20
+ "test:ci": "jest --ci --coverage --watchAll=false",
21
+ "build": "tsc",
22
+ "clean": "rimraf dist",
23
+ "prebuild": "npm run clean",
24
+ "start": "node dist/cli/index.js",
25
+ "dev": "npm run build && npm start",
26
+ "lint": "prettier --write",
27
+ "generate": "npm run build && node dist/cli/index.js generate",
28
+ "init": "npm run build && node dist/cli/index.js init",
29
+ "validate": "npm run build && node dist/cli/index.js validate",
30
+ "swagger:generate": "npm run generate",
31
+ "swagger:run": "npm run generate",
32
+ "swagger:init": "npm run init",
33
+ "swagger:validate": "npm run validate"
34
+ },
35
+ "keywords": [
36
+ "swagger",
37
+ "openapi",
38
+ "typescript",
39
+ "api",
40
+ "generator",
41
+ "cli",
42
+ "code-generation"
43
+ ],
44
+ "author": "xiaoyang",
45
+ "license": "MIT",
46
+ "homepage": "https://github.com/xiaoyang33/swagger2api-v3#readme",
47
+ "repository": {
48
+ "type": "git",
49
+ "url": "https://github.com/xiaoyang33/swagger2api-v3.git"
50
+ },
51
+ "bugs": {
52
+ "url": "https://github.com/xiaoyang33/swagger2api-v3/issues"
53
+ },
54
+ "packageManager": "pnpm@10.11.0",
55
+ "devDependencies": {
56
+ "@types/jest": "^29.5.0",
57
+ "@types/node": "^24.3.1",
58
+ "jest": "^29.5.0",
59
+ "prettier": "^3.6.2",
60
+ "rimraf": "^6.0.1",
61
+ "ts-jest": "^29.1.0",
62
+ "typescript": "^5.9.2"
63
+ },
64
+ "dependencies": {
65
+ "axios": "^1.11.0",
66
+ "commander": "^12.0.0"
67
+ }
68
+ }