swagger2api-v3 1.0.8 → 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 -196
  2. package/dist/cli/index.js +41 -40
  3. package/package.json +68 -68
package/README.md CHANGED
@@ -1,197 +1,199 @@
1
- # Swagger2API-v3
2
-
3
- 一个强大的命令行工具，用于从 Swagger(OAS3.0) 文档自动生成 TypeScript 接口代码。
4
-
5
- ## ✨ 特性
6
-
7
- - 🚀 **快速生成** - 从 Swagger JSON 快速生成 TypeScript 接口代码
8
- - 📁 **智能分组** - 支持按 Swagger 标签自动分组生成文件
9
- - 📝 **详细注释** - 自动生成包含描述、参数、返回值的详细注释
10
- - 🎨 **代码格式化** - 支持自定义格式化命令
11
- - ⚙️ **环境适配** - 自动检测项目环境，生成对应格式的配置文件
12
- - 🔧 **CLI 工具** - 提供完整的命令行工具
13
-
14
- ## 📦 安装
15
-
16
- ```bash
17
- # 全局安装
18
- npm install -g swagger2api-v3
19
-
20
- # 项目依赖
21
- npm install swagger2api-v3
22
- ```
23
-
24
- ## 🚀 快速开始
25
-
26
- ### 1. 初始化配置文件
27
-
28
- ```bash
29
- npx swagger2api-v3 init
30
- ```
31
-
32
- ### 2. 配置文件说明
33
-
34
- 工具会根据项目环境自动生成对应格式的配置文件：
35
-
36
- **CommonJS 环境** (`"type": "commonjs"` 或未设置)：
37
- ```javascript
38
- const config = {
39
- input: 'https://petstore.swagger.io/v2/swagger.json',
40
- output: './src/api',
41
- importTemplate: "import { request } from '@/utils/request';",
42
- generator: 'typescript',
43
- groupByTags: true,
44
- overwrite: true,
45
- prefix: '',
46
- lint: 'prettier --write',
47
- options: {
48
- addComments: true
49
- }
50
- };
51
-
52
- module.exports = config;
53
- ```
54
-
55
- **ES 模块环境** (`"type": "module"`)：
56
- ```javascript
57
- const config = {
58
- // ... 相同配置
59
- };
60
-
61
- export default config;
62
- ```
63
-
64
- ### 3. 生成接口代码
65
-
66
- ```bash
67
- npx swagger2api-v3 generate
68
- ```
69
-
70
- ## ⚙️ 配置选项
71
-
72
- | 选项 | 类型 | 默认值 | 说明 |
73
- |------|------|--------|------|
74
- | `input` | string | - | Swagger JSON 文件路径或 URL |
75
- | `output` | string | `'./src/api'` | 生成代码的输出目录 |
76
- | `generator` | string | `'typescript'` | 代码生成器类型 |
77
- | `groupByTags` | boolean | `true` | 是否按标签分组生成文件 |
78
- | `overwrite` | boolean | `true` | 是否覆盖已存在的文件 |
79
- | `prefix` | string | `''` | 接口路径公共前缀 |
80
- | `importTemplate` | string | - | request 函数导入语句模板 |
81
- | `lint` | string | - | 代码格式化命令（可选） |
82
- | `options.addComments` | boolean | `true` | 是否添加详细注释 |
83
-
84
- ## 📁 生成的文件结构
85
-
86
- ### 按标签分组 (推荐)
87
-
88
- ```
89
- src/api/
90
- ├── types.ts # 数据类型定义
91
- ├── user/ # User 相关接口
92
- │ └── index.ts
93
- ├── auth/ # Auth 相关接口
94
- │ └── index.ts
95
- └── index.ts # 入口文件
96
- ```
97
-
98
- ### 不分组
99
-
100
- ```
101
- src/api/
102
- ├── types.ts # 数据类型定义
103
- ├── api.ts # 所有 API 接口
104
- └── index.ts # 入口文件
105
- ```
106
-
107
- ## 💡 使用示例
108
-
109
- ### 生成的类型定义
110
-
111
- ```typescript
112
- // types.ts
113
- export interface LoginDto {
114
- /** 账号 */
115
- account: string;
116
- /** 密码 */
117
- password: string;
118
- }
119
-
120
- export interface UserInfo {
121
- /** 用户ID */
122
- id: string;
123
- /** 用户名 */
124
- username: string;
125
- }
126
- ```
127
-
128
- ### 生成的 API 接口
129
-
130
- ```typescript
131
- // authController/index.ts
132
- import { request } from '@/utils/request';
133
- import type { LoginDto, LoginRespDto } from '../types';
134
-
135
- /**
136
- * 登录
137
- * @param data 登录参数
138
- * @param config 可选的请求配置
139
- */
140
- export const authControllerLoginPost = (data: LoginDto, config?: any) => {
141
- return request.post<LoginRespDto>({
142
- url: '/admin/auth/login',
143
- data,
144
- ...config
145
- });
146
- };
147
- ```
148
-
149
- ## 🔧 CLI 命令
150
-
151
- ```bash
152
- # 初始化配置文件
153
- npx swagger2api-v3 init [--force]
154
-
155
- # 生成接口代码
156
- npx swagger2api-v3 generate [--config <path>]
157
-
158
- # 验证配置文件
159
- npx swagger2api-v3 validate [--config <path>]
160
-
161
- # 查看帮助
162
- npx swagger2api-v3 --help
163
- ```
164
-
165
- ## 📝 NPM 脚本
166
-
167
- 在 `package.json` 中添加：
168
-
169
- ```json
170
- {
171
- "scripts": {
172
- "api:generate": "swagger2api-v3 generate",
173
- "api:init": "swagger2api-v3 init",
174
- "api:validate": "swagger2api-v3 validate"
175
- }
176
- }
177
- ```
178
-
179
- ## 🎨 代码格式化
180
-
181
- 支持在生成完成后自动执行格式化命令：
182
-
183
- ```javascript
184
- // 配置文件中
185
- const config = {
186
- // ... 其他配置
187
- lint: 'prettier --write' // 或 'eslint --fix' 等
188
- };
189
- ```
190
-
191
- ## 🤝 贡献
192
-
193
- 欢迎提交 Issue 和 Pull Request！
194
-
195
- ## 📄 许可证
196
-
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
+
197
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.8",
4
- "description": "从 Swagger/OpenAPI 文档生成 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
+ }