@vc-shell/api-client-generator 2.0.3-pr227.0c4f2c3 → 2.0.3-pr229.9dc1748
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.
- package/README.md +37 -26
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -49,25 +49,20 @@ Add the dependencies to your project's **package.json**:
|
|
|
49
49
|
{
|
|
50
50
|
"scripts": {
|
|
51
51
|
...
|
|
52
|
-
"generate-api-client": cross-env api-client-generator
|
|
52
|
+
"generate-api-client": "cross-env api-client-generator"
|
|
53
53
|
}
|
|
54
54
|
}
|
|
55
55
|
```
|
|
56
56
|
|
|
57
57
|
The options are listed in the table below:
|
|
58
58
|
|
|
59
|
-
| Options | Description | Example
|
|
60
|
-
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
61
|
-
| `--APP_PLATFORM_MODULES` | Platform modules to generate API client.<br>{==string[]==} <br> Supports spaces in module lists: `[Module1, Module2]` or `[Module1,Module2]`<br>Customize the `--APP_PLATFORM_MODULES` list<br>to match your project's requirements. | `--APP_PLATFORM_MODULES='[
|
|
62
|
-
| `--APP_API_CLIENT_DIRECTORY` | Output directory for generated API clients. <br>{==string==} | `--APP_API_CLIENT_DIRECTORY=./src/api_client/`
|
|
63
|
-
| `--APP_PLATFORM_URL` | Platform URL to obtain client API configs. <br>{==string==} | `--APP_PLATFORM_URL=https://vcmp-dev.govirto.com/`
|
|
64
|
-
| `--
|
|
65
|
-
| `--
|
|
66
|
-
| `--APP_OUT_DIR` | Output directory for generated API clients. <br>{==string==} | `--APP_OUT_DIR=./src/api_client/` |
|
|
67
|
-
| `--APP_TYPE_STYLE` | Sets the type style for generated DTOs. Can be 'Class' or 'Interface'.<br>{==string==} | `--APP_TYPE_STYLE=Interface` |
|
|
68
|
-
| `--APP_BUILD_DIR` | Directory where TypeScript files will be compiled. <br>{==string==} | `--APP_BUILD_DIR=lib` (default is "dist") |
|
|
69
|
-
| `--SKIP_BUILD` | Skip build step. <br>{==boolean==} | `--SKIP_BUILD=true` |
|
|
70
|
-
| `--VERBOSE` | Enable verbose logging. <br>{==boolean==} | `--VERBOSE=true` |
|
|
59
|
+
| Options | Description | Example |
|
|
60
|
+
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
|
|
61
|
+
| `--APP_PLATFORM_MODULES` | Platform modules to generate API client.<br>{==string[]==} <br> Supports spaces in module lists: `[Module1, Module2]` or `[Module1,Module2]`<br>Customize the `--APP_PLATFORM_MODULES` list<br>to match your project's requirements. | `--APP_PLATFORM_MODULES='[VirtoCommerce.Catalog, VirtoCommerce.Orders]'` |
|
|
62
|
+
| `--APP_API_CLIENT_DIRECTORY` | Output directory for generated API clients. <br>{==string==} | `--APP_API_CLIENT_DIRECTORY=./src/api_client/` |
|
|
63
|
+
| `--APP_PLATFORM_URL` | Platform URL to obtain client API configs. <br>{==string==} | `--APP_PLATFORM_URL=https://vcmp-dev.govirto.com/` |
|
|
64
|
+
| `--APP_TYPE_STYLE` | Sets the type style for generated DTOs. Can be 'Class' or 'Interface'.<br>{==string==} | `--APP_TYPE_STYLE=Interface` |
|
|
65
|
+
| `--VERBOSE` | Enable verbose logging. <br>{==boolean==} | `--VERBOSE=true` |
|
|
71
66
|
|
|
72
67
|
!!! note
|
|
73
68
|
For the `--APP_TYPE_STYLE` parameter, use **exactly** `"Class"` or `"Interface"` (case-sensitive). Any other value will cause an error.
|
|
@@ -78,19 +73,29 @@ Add the dependencies to your project's **package.json**:
|
|
|
78
73
|
3. Configure Platform URL and other settings in your project's **.env** file:
|
|
79
74
|
|
|
80
75
|
```title="vc-app-extend/.env"
|
|
81
|
-
|
|
82
|
-
APP_PLATFORM_MODULES=[Virtocommerce.MarketplaceVendor,Virtocommerce.Catalog,Virtocommerce.Orders]
|
|
76
|
+
APP_PLATFORM_MODULES=[VirtoCommerce.Catalog,VirtoCommerce.Orders]
|
|
83
77
|
APP_API_CLIENT_DIRECTORY=./src/api_client/
|
|
84
|
-
|
|
85
|
-
APP_PACKAGE_VERSION=1.0.0
|
|
86
|
-
APP_BUILD_DIR=dist
|
|
87
|
-
VERBOSE=true
|
|
88
|
-
SKIP_BUILD=false
|
|
78
|
+
APP_TYPE_STYLE=Interface
|
|
89
79
|
```
|
|
90
80
|
|
|
91
81
|
!!! note
|
|
92
82
|
All configuration options can be set via environment variables in `.env` file or passed as command line arguments. Environment variables take precedence over CLI arguments.
|
|
93
83
|
|
|
84
|
+
!!! tip
|
|
85
|
+
Keep machine-specific Platform URLs out of shared `.env` files. Set `APP_PLATFORM_URL` in `.env.local`, in your shell, or pass `--APP_PLATFORM_URL=...` when running the generator.
|
|
86
|
+
|
|
87
|
+
The minimal `.env` above is enough for the default generation mode. By default, the generator writes TypeScript client files into `APP_API_CLIENT_DIRECTORY`; it does not create a generated API package or `package.json`.
|
|
88
|
+
|
|
89
|
+
Package mode is optional. Use it only when you intentionally maintain a generated API package. Package mode is enabled with `--PACKAGE=true` or when a `package.json` already exists in `APP_API_CLIENT_DIRECTORY`. In package mode, these additional options apply:
|
|
90
|
+
|
|
91
|
+
| Options | Description | Example |
|
|
92
|
+
| ----------------------- | ---------------------------------------------------- | -------------------------------- |
|
|
93
|
+
| `--APP_PACKAGE_NAME` | Package name for generated API clients. | `--APP_PACKAGE_NAME=@my-app/api` |
|
|
94
|
+
| `--APP_PACKAGE_VERSION` | Package version for generated API clients. | `--APP_PACKAGE_VERSION=1.1.0` |
|
|
95
|
+
| `--APP_OUT_DIR` | Output directory used by generated package metadata. | `--APP_OUT_DIR=dist` |
|
|
96
|
+
| `--APP_BUILD_DIR` | Directory where TypeScript files will be compiled. | `--APP_BUILD_DIR=lib` |
|
|
97
|
+
| `--SKIP_BUILD` | Skip build step. | `--SKIP_BUILD=true` |
|
|
98
|
+
|
|
94
99
|
4. Generate the API clients using the following command:
|
|
95
100
|
|
|
96
101
|
```
|
|
@@ -103,15 +108,15 @@ This command generates the required API clients for your custom application. Now
|
|
|
103
108
|
|
|
104
109
|
### Smart Configuration Merging
|
|
105
110
|
|
|
106
|
-
|
|
111
|
+
When package mode is enabled, the generator intelligently merges configuration files to preserve your custom settings. When you update an existing generated API package:
|
|
107
112
|
|
|
108
113
|
- Custom package.json fields like name, version, description, keywords, author and license are preserved
|
|
109
114
|
- Custom tsconfig.json settings are maintained
|
|
110
115
|
- Exports are intelligently updated to preserve existing paths
|
|
111
116
|
|
|
112
|
-
### Metadata Tracking
|
|
117
|
+
### Package Metadata Tracking
|
|
113
118
|
|
|
114
|
-
API
|
|
119
|
+
When package mode is enabled, the generated API package includes metadata to track the generation:
|
|
115
120
|
|
|
116
121
|
```json
|
|
117
122
|
{
|
|
@@ -124,6 +129,8 @@ API client now includes metadata to track the generation:
|
|
|
124
129
|
|
|
125
130
|
### Multiple API Exports
|
|
126
131
|
|
|
132
|
+
This applies when package mode is enabled.
|
|
133
|
+
|
|
127
134
|
The generator handles multiple API clients effectively:
|
|
128
135
|
|
|
129
136
|
- Creates standardized exports with both short names (`./{moduleName}`) and full names (`./virtocommerce.{moduleName}`)
|
|
@@ -133,6 +140,8 @@ The generator handles multiple API clients effectively:
|
|
|
133
140
|
|
|
134
141
|
### Smart Root Export Handling
|
|
135
142
|
|
|
143
|
+
This applies when package mode is enabled.
|
|
144
|
+
|
|
136
145
|
The generator now intelligently handles root exports based on the number of API modules:
|
|
137
146
|
|
|
138
147
|
- **Single API Module**: When only one API module is generated, it automatically becomes the root export (`.`) and `module`/`types` fields are maintained
|
|
@@ -164,6 +173,8 @@ yarn generate-api-client --VERBOSE=true
|
|
|
164
173
|
|
|
165
174
|
### Custom Build Directory
|
|
166
175
|
|
|
176
|
+
This applies when package mode is enabled.
|
|
177
|
+
|
|
167
178
|
You can specify a custom build directory where TypeScript files will be compiled:
|
|
168
179
|
|
|
169
180
|
```
|
|
@@ -215,9 +226,9 @@ If you encounter issues during API client generation:
|
|
|
215
226
|
2. Ensure target directories have proper permissions
|
|
216
227
|
3. Check your connectivity to the platform URL
|
|
217
228
|
4. Verify that the specified platform modules exist
|
|
218
|
-
5. If you encounter JSON parsing errors in tsconfig.json or package.json, try using the `--VERBOSE=true` flag to see detailed error messages
|
|
219
|
-
6.
|
|
220
|
-
7. If you manually modified exports in package.json, ensure they follow the correct format
|
|
229
|
+
5. If package mode is enabled and you encounter JSON parsing errors in tsconfig.json or package.json, try using the `--VERBOSE=true` flag to see detailed error messages
|
|
230
|
+
6. If package mode is enabled, check for duplicate exports in package.json which might cause conflicts
|
|
231
|
+
7. If package mode is enabled and you manually modified exports in package.json, ensure they follow the correct format
|
|
221
232
|
|
|
222
233
|
### Common Issues
|
|
223
234
|
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@vc-shell/api-client-generator",
|
|
3
3
|
"description": "Tool for API clients generation",
|
|
4
|
-
"version": "2.0.3-
|
|
4
|
+
"version": "2.0.3-pr229.9dc1748",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": "./dist/api-client-generator.js",
|
|
7
7
|
"files": [
|
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
},
|
|
14
14
|
"devDependencies": {
|
|
15
15
|
"@types/cross-spawn": "^6.0.6",
|
|
16
|
-
"@vc-shell/ts-config": "2.0.3-
|
|
16
|
+
"@vc-shell/ts-config": "2.0.3-pr229.9dc1748",
|
|
17
17
|
"typescript": "^5.8.3"
|
|
18
18
|
},
|
|
19
19
|
"dependencies": {
|