anl 26.107.0 → 26.107.2
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.ar.md +59 -59
- package/README.es.md +59 -59
- package/README.fr.md +106 -106
- package/README.jp.md +56 -56
- package/README.md +131 -67
- package/README.ru.md +56 -56
- package/README.zh.md +144 -78
- package/lib/package.json.js +1 -1
- package/lib/src/build-type/core/get-data.js +1 -1
- package/lib/src/build-type/core/path.js +1 -1
- package/lib/src/build-type/index.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -104,7 +104,7 @@ $ anl type
|
|
|
104
104
|
"saveApiListFolderPath": "apps/api/",
|
|
105
105
|
"saveEnumFolderPath": "apps/enums",
|
|
106
106
|
"importEnumPath": "../../enums",
|
|
107
|
-
"
|
|
107
|
+
"swaggerConfig": {
|
|
108
108
|
"url": "https://generator3.swagger.io/openapi2.json",
|
|
109
109
|
"apiListFileName": "index.ts",
|
|
110
110
|
"publicPrefix": "api",
|
|
@@ -120,7 +120,8 @@ $ anl type
|
|
|
120
120
|
"includeInterface": [
|
|
121
121
|
{
|
|
122
122
|
"path": "/api/user",
|
|
123
|
-
"method": "get"
|
|
123
|
+
"method": "get",
|
|
124
|
+
"dataLevel": "data"
|
|
124
125
|
}
|
|
125
126
|
],
|
|
126
127
|
"excludeInterface": [
|
|
@@ -158,7 +159,7 @@ $ anl type
|
|
|
158
159
|
"varnames": "enum-varnames",
|
|
159
160
|
"comment": "enum-descriptions"
|
|
160
161
|
},
|
|
161
|
-
"
|
|
162
|
+
"swaggerConfig": [
|
|
162
163
|
{
|
|
163
164
|
"url": "https://generator3.swagger.io/openapi1.json",
|
|
164
165
|
"apiListFileName": "op.ts",
|
|
@@ -176,41 +177,41 @@ $ anl type
|
|
|
176
177
|
|
|
177
178
|
#### Configuration Item Descriptions
|
|
178
179
|
|
|
179
|
-
| Configuration Item
|
|
180
|
-
|
|
|
181
|
-
| saveTypeFolderPath
|
|
182
|
-
| saveApiListFolderPath
|
|
183
|
-
| saveEnumFolderPath
|
|
184
|
-
| importEnumPath
|
|
185
|
-
| swaggerJsonUrl
|
|
186
|
-
|
|
|
187
|
-
|
|
|
188
|
-
|
|
|
189
|
-
|
|
|
190
|
-
|
|
|
191
|
-
|
|
|
192
|
-
|
|
|
193
|
-
|
|
|
194
|
-
|
|
|
195
|
-
|
|
|
196
|
-
| requestMethodsImportPath
|
|
197
|
-
| dataLevel
|
|
198
|
-
| formatting
|
|
199
|
-
| formatting.indentation
|
|
200
|
-
| formatting.lineEnding
|
|
201
|
-
| headers
|
|
202
|
-
| includeInterface
|
|
203
|
-
| excludeInterface
|
|
204
|
-
| publicPrefix
|
|
205
|
-
|
|
|
206
|
-
| apiListFileName
|
|
207
|
-
| enmuConfig
|
|
208
|
-
| enmuConfig.erasableSyntaxOnly
|
|
209
|
-
| enmuConfig.varnames
|
|
210
|
-
| enmuConfig.comment
|
|
211
|
-
| parameterSeparator
|
|
212
|
-
| enmuConfig.varnames
|
|
213
|
-
| enmuConfig.comment
|
|
180
|
+
| Configuration Item | Type | Required | Description |
|
|
181
|
+
| ---------------------------------- | ------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
182
|
+
| saveTypeFolderPath | string | Yes | Type definition file save path |
|
|
183
|
+
| saveApiListFolderPath | string | Yes | API request function file save path |
|
|
184
|
+
| saveEnumFolderPath | string | Yes | Enum data file save path |
|
|
185
|
+
| importEnumPath | string | Yes | Enum import path (path referenced by enum files in apps/types/models/\*.ts) |
|
|
186
|
+
| swaggerJsonUrl | string | No | Swagger JSON documentation address (migrated to `swaggerConfig`, retained for backward compatibility) **This field will be removed in future versions** |
|
|
187
|
+
| swaggerConfig | object \| Array<object> | No | Swagger server configuration. Single server can be an object, multiple servers use an array. Each server can configure `url`, `publicPrefix`, `modulePrefix`, `apiListFileName`, `headers`, `dataLevel`, `parameterSeparator`, `includeInterface`, `excludeInterface`<br />See single and multiple Swagger server configuration examples above |
|
|
188
|
+
| swaggerConfig[].url | string | Yes | Swagger JSON documentation address |
|
|
189
|
+
| swaggerConfig[].publicPrefix | string | No | Common prefix on url path, e.g.: api/users, api/users/{id}, api is the common prefix |
|
|
190
|
+
| swaggerConfig[].apiListFileName | string | No | API list file name, defaults to `index.ts`. When using multiple servers, each server's file name must be unique |
|
|
191
|
+
| swaggerConfig[].headers | object | No | Request header configuration for this server |
|
|
192
|
+
| swaggerConfig[].modulePrefix | string | No | Request path prefix (can be understood as module name), automatically added to the front of each API request path.<br />For example: when `modulePrefix: "/forward"`<br />`/publicPrefix/modulePrefix/user` becomes `/api/forward/user` |
|
|
193
|
+
| swaggerConfig[].dataLevel | 'data' \| 'serve' \| 'axios' | No | Interface return data level for this server. If not set, uses global `dataLevel` configuration |
|
|
194
|
+
| swaggerConfig[].parameterSeparator | '$' \| '\_' | No | Separator used when generating API names and type names for this server. If not set, uses global `parameterSeparator` configuration |
|
|
195
|
+
| swaggerConfig[].includeInterface | Array<{path: string, method: string, dataLevel?: 'data' \| 'serve' \| 'axios'}> | No | List of interfaces to include for this server. Each interface can configure `dataLevel` individually with the highest priority. If not set, uses global `includeInterface` configuration |
|
|
196
|
+
| swaggerConfig[].excludeInterface | Array<{path: string, method: string}> | No | List of interfaces to exclude for this server. If not set, uses global `excludeInterface` configuration |
|
|
197
|
+
| requestMethodsImportPath | string | Yes | Request method import path |
|
|
198
|
+
| dataLevel | 'data' \| 'serve' \| 'axios' | No | Global interface return data level configuration, default: `'serve'`. Each server can override individually |
|
|
199
|
+
| formatting | object | No | Code formatting configuration |
|
|
200
|
+
| formatting.indentation | string | No | Code indentation character, e.g.: `"\t"` or `" "` (two spaces) |
|
|
201
|
+
| formatting.lineEnding | string | No | Line ending, e.g.: `"\n"` (LF) or `"\r\n"` (CRLF) |
|
|
202
|
+
| headers | object | No | Request header configuration (migrated to `swaggerConfig`, retained for backward compatibility) |
|
|
203
|
+
| includeInterface | Array<{path: string, method: string, dataLevel?: 'data' \| 'serve' \| 'axios'}> | No | Global included interfaces: The interface list file specified by `saveApiListFolderPath` will only include interfaces in the list, mutually exclusive with `excludeInterface` field. Each interface can configure `dataLevel` individually. Each server can override individually |
|
|
204
|
+
| excludeInterface | Array<{path: string, method: string}> | No | Global excluded interfaces: The interface list file specified by `saveApiListFolderPath` will not include interfaces in this list, mutually exclusive with `includeInterface`. Each server can override individually |
|
|
205
|
+
| publicPrefix | string | No | Global common prefix on url path (migrated to `swaggerConfig`, retained for backward compatibility) |
|
|
206
|
+
| modulePrefix | string | No | Global request path prefix (each server can override individually) |
|
|
207
|
+
| apiListFileName | string | No | Global API list file name, defaults to `index.ts` (migrated to `swaggerConfig`, retained for backward compatibility) |
|
|
208
|
+
| enmuConfig | object | Yes | Enum configuration object |
|
|
209
|
+
| enmuConfig.erasableSyntaxOnly | boolean | Yes | Align with tsconfig.json `compilerOptions.erasableSyntaxOnly`. When `true`, generates const objects instead of enums (type-only syntax). Default: `false` |
|
|
210
|
+
| enmuConfig.varnames | string | No | Swagger schema field name for custom enum member names. Default: `enum-varnames`. |
|
|
211
|
+
| enmuConfig.comment | string | No | Swagger schema field name for custom enum descriptions (used for generating comments). Default: `enum-descriptions`. |
|
|
212
|
+
| parameterSeparator | '$' \| '\_' | No | Global separator used between path segments and parameters when generating API names and type names. For example, `/users/{userId}/posts` with separator `'_'` generates `users_userId_posts_GET`. Default: `'_'`. Each server can override individually |
|
|
213
|
+
| enmuConfig.varnames | string | No | Schema field name that stores custom enum member identifiers. Default: `enum-varnames`. |
|
|
214
|
+
| enmuConfig.comment | string | No | Schema field name that stores enum member descriptions (used for inline comments). Default: `enum-descriptions`. |
|
|
214
215
|
|
|
215
216
|
#### Configuration Items and Generated Files Correspondence
|
|
216
217
|
|
|
@@ -268,15 +269,19 @@ export const userDetailGet = (params: UserDetail_GET.Query) => GET<UserDetail_GE
|
|
|
268
269
|
|
|
269
270
|
The tool supports global configuration and server-level configuration, following these priority rules:
|
|
270
271
|
|
|
271
|
-
**Priority: Server-level configuration > Global configuration > Default values**
|
|
272
|
+
**Priority: Interface-level configuration > Server-level configuration > Global configuration > Default values**
|
|
272
273
|
|
|
273
|
-
The following configuration items support
|
|
274
|
+
The following configuration items support multi-level priority override:
|
|
274
275
|
|
|
275
276
|
- `dataLevel`: Interface return data level
|
|
277
|
+
- **Interface-level**: `includeInterface[].dataLevel` - Highest priority
|
|
278
|
+
- **Server-level**: `swaggerConfig[].dataLevel` - Secondary priority
|
|
279
|
+
- **Global configuration**: `dataLevel` - Base priority
|
|
280
|
+
- **Default value**: `'serve'`
|
|
276
281
|
- `parameterSeparator`: Separator for API names and type names
|
|
277
282
|
- `includeInterface`: List of included interfaces
|
|
278
283
|
- `excludeInterface`: List of excluded interfaces
|
|
279
|
-
- `
|
|
284
|
+
- `modulePrefix`: Request path prefix
|
|
280
285
|
- `publicPrefix`: URL common prefix
|
|
281
286
|
- `headers`: Request header configuration
|
|
282
287
|
|
|
@@ -286,7 +291,7 @@ The following configuration items support server-level override of global config
|
|
|
286
291
|
{
|
|
287
292
|
"dataLevel": "serve",
|
|
288
293
|
"parameterSeparator": "_",
|
|
289
|
-
"
|
|
294
|
+
"swaggerConfig": [
|
|
290
295
|
{
|
|
291
296
|
"url": "http://api1.example.com/swagger.json",
|
|
292
297
|
"dataLevel": "data",
|
|
@@ -380,21 +385,48 @@ interface User {
|
|
|
380
385
|
// Function returns: { code: 200, message: 'success', data: { id: 1, name: 'user' } }
|
|
381
386
|
```
|
|
382
387
|
|
|
388
|
+
**Configuration Priority:**
|
|
389
|
+
|
|
390
|
+
`dataLevel` supports three-level configuration priority:
|
|
391
|
+
|
|
392
|
+
```
|
|
393
|
+
Interface-level > Server-level > Global configuration > Default value
|
|
394
|
+
```
|
|
395
|
+
|
|
383
396
|
**Configuration example:**
|
|
384
397
|
|
|
385
398
|
```json
|
|
386
399
|
{
|
|
387
400
|
"dataLevel": "serve",
|
|
388
|
-
"
|
|
401
|
+
"swaggerConfig": [
|
|
389
402
|
{
|
|
390
403
|
"url": "http://api1.example.com/swagger.json",
|
|
391
|
-
"dataLevel": "data"
|
|
404
|
+
"dataLevel": "data",
|
|
405
|
+
"includeInterface": [
|
|
406
|
+
{
|
|
407
|
+
"path": "/api/user/detail",
|
|
408
|
+
"method": "get",
|
|
409
|
+
"dataLevel": "axios"
|
|
410
|
+
},
|
|
411
|
+
{
|
|
412
|
+
"path": "/api/user/list",
|
|
413
|
+
"method": "get"
|
|
414
|
+
}
|
|
415
|
+
]
|
|
392
416
|
}
|
|
393
417
|
]
|
|
394
418
|
}
|
|
395
419
|
```
|
|
396
420
|
|
|
397
|
-
|
|
421
|
+
In the above configuration:
|
|
422
|
+
- `/api/user/detail` interface uses `dataLevel: "axios"` (interface-level configuration, highest priority)
|
|
423
|
+
- `/api/user/list` interface uses `dataLevel: "data"` (server-level configuration)
|
|
424
|
+
- Other server interfaces use `dataLevel: "serve"` (global configuration)
|
|
425
|
+
|
|
426
|
+
> **Note**:
|
|
427
|
+
> - Interface-level `dataLevel` configuration has the highest priority, suitable for scenarios where individual interfaces need special handling
|
|
428
|
+
> - Server-level `dataLevel` configuration will override global configuration
|
|
429
|
+
> - Uses default value `'serve'` when not configured
|
|
398
430
|
|
|
399
431
|
#### Code Formatting
|
|
400
432
|
|
|
@@ -449,7 +481,8 @@ The tool supports filtering interfaces to be generated through configuration:
|
|
|
449
481
|
1. Include specific interfaces
|
|
450
482
|
- Specify interfaces to be generated through the `includeInterface` configuration item
|
|
451
483
|
- Only interfaces specified in the configuration will be generated
|
|
452
|
-
- Configuration format is an object array containing `path` and `
|
|
484
|
+
- Configuration format is an object array containing `path`, `method`, and optional `dataLevel`
|
|
485
|
+
- Each interface can configure `dataLevel` individually with the highest priority
|
|
453
486
|
|
|
454
487
|
2. Exclude specific interfaces
|
|
455
488
|
- Specify interfaces to be excluded through the `excludeInterface` configuration item
|
|
@@ -463,7 +496,8 @@ Example configuration: This configuration is in `an.config.json`
|
|
|
463
496
|
"includeInterface": [
|
|
464
497
|
{
|
|
465
498
|
"path": "/api/user",
|
|
466
|
-
"method": "get"
|
|
499
|
+
"method": "get",
|
|
500
|
+
"dataLevel": "data"
|
|
467
501
|
}
|
|
468
502
|
],
|
|
469
503
|
"excludeInterface": [
|
|
@@ -481,8 +515,8 @@ Note: `includeInterface` and `excludeInterface` cannot be used simultaneously. I
|
|
|
481
515
|
|
|
482
516
|
The tool supports configuring multiple Swagger servers, each server can be configured independently:
|
|
483
517
|
|
|
484
|
-
- **Single server**: `
|
|
485
|
-
- **Multiple servers**: `
|
|
518
|
+
- **Single server**: `swaggerConfig` can be directly filled with an object
|
|
519
|
+
- **Multiple servers**: `swaggerConfig` uses an array format, each server must configure a unique `apiListFileName`
|
|
486
520
|
|
|
487
521
|
**How it works:**
|
|
488
522
|
|
|
@@ -498,11 +532,11 @@ Each server supports independent configuration of the following options. If not
|
|
|
498
532
|
- `parameterSeparator` - Separator for API names and type names
|
|
499
533
|
- `includeInterface` - List of included interfaces
|
|
500
534
|
- `excludeInterface` - List of excluded interfaces
|
|
501
|
-
- `
|
|
535
|
+
- `modulePrefix` - Request path prefix
|
|
502
536
|
|
|
503
|
-
#### Path Prefix (
|
|
537
|
+
#### Path Prefix (modulePrefix)
|
|
504
538
|
|
|
505
|
-
`
|
|
539
|
+
`modulePrefix` is used to automatically add a prefix to all API request paths, which is particularly useful in the following scenarios:
|
|
506
540
|
|
|
507
541
|
1. **Reverse proxy scenarios**: When backend services are forwarded through a reverse proxy
|
|
508
542
|
2. **API Gateway**: Uniformly add gateway prefix to paths
|
|
@@ -512,10 +546,10 @@ Each server supports independent configuration of the following options. If not
|
|
|
512
546
|
|
|
513
547
|
```json
|
|
514
548
|
{
|
|
515
|
-
"
|
|
549
|
+
"swaggerConfig": [
|
|
516
550
|
{
|
|
517
551
|
"url": "http://api.example.com/swagger.json",
|
|
518
|
-
"
|
|
552
|
+
"modulePrefix": "/forward",
|
|
519
553
|
"apiListFileName": "api.ts"
|
|
520
554
|
}
|
|
521
555
|
]
|
|
@@ -533,18 +567,18 @@ export const apiUserListGet = (params: ApiUserList_GET.Query) => GET<ApiUserList
|
|
|
533
567
|
**Difference from publicPrefix:**
|
|
534
568
|
|
|
535
569
|
- `publicPrefix`: Used to remove common prefix from interface paths (only affects generated function names)
|
|
536
|
-
- `
|
|
570
|
+
- `modulePrefix`: Used to add prefix to actual request paths (affects runtime request URLs)
|
|
537
571
|
|
|
538
572
|
**Configuration example:**
|
|
539
573
|
|
|
540
574
|
```json
|
|
541
575
|
{
|
|
542
|
-
"
|
|
576
|
+
"swaggerConfig": [
|
|
543
577
|
{
|
|
544
578
|
"url": "http://api1.example.com/swagger.json",
|
|
545
579
|
"apiListFileName": "api1.ts",
|
|
546
580
|
"publicPrefix": "/api/v1",
|
|
547
|
-
"
|
|
581
|
+
"modulePrefix": "/forward",
|
|
548
582
|
"dataLevel": "serve",
|
|
549
583
|
"parameterSeparator": "_",
|
|
550
584
|
"headers": {
|
|
@@ -574,7 +608,7 @@ export const apiUserListGet = (params: ApiUserList_GET.Query) => GET<ApiUserList
|
|
|
574
608
|
|
|
575
609
|
- Old configuration (`swaggerJsonUrl`, `publicPrefix`, `headers`) is still compatible
|
|
576
610
|
- The tool will automatically detect old configuration and suggest migration methods
|
|
577
|
-
- It's recommended to migrate to the new `
|
|
611
|
+
- It's recommended to migrate to the new `swaggerConfig` configuration for better flexibility
|
|
578
612
|
|
|
579
613
|
#### HTTP Method Support
|
|
580
614
|
|
|
@@ -599,7 +633,7 @@ All methods support type-safe parameter and response type definitions.
|
|
|
599
633
|
4. It's recommended to add generated files to version control
|
|
600
634
|
5. When using multiple Swagger servers, ensure each server's `apiListFileName` is unique to avoid file overwriting
|
|
601
635
|
6. When configuring multiple servers, type definitions and enums will be merged. If different servers have types with the same name, conflicts may occur
|
|
602
|
-
7. Server-level configuration (`dataLevel`, `parameterSeparator`, `includeInterface`, `excludeInterface`, `
|
|
636
|
+
7. Server-level configuration (`dataLevel`, `parameterSeparator`, `includeInterface`, `excludeInterface`, `modulePrefix`) will override global configuration
|
|
603
637
|
8. `includeInterface` and `excludeInterface` cannot be configured simultaneously. If both are configured, `includeInterface` will be prioritized
|
|
604
638
|
|
|
605
639
|
### Common Issues
|
|
@@ -613,15 +647,15 @@ All methods support type-safe parameter and response type definitions.
|
|
|
613
647
|
- Check if the `requestMethodsImportPath` configuration is correct
|
|
614
648
|
- Confirm if the request method file exists
|
|
615
649
|
|
|
616
|
-
3. **When to use `
|
|
650
|
+
3. **When to use `modulePrefix`?**
|
|
617
651
|
- When your APIs need to be accessed through a reverse proxy or gateway
|
|
618
652
|
- For example: Swagger defines `/api/user`, but the actual request needs to be `/gateway/api/user`
|
|
619
|
-
- Set `
|
|
653
|
+
- Set `modulePrefix: "/gateway"` to achieve this
|
|
620
654
|
|
|
621
|
-
4. **What's the difference between `publicPrefix` and `
|
|
655
|
+
4. **What's the difference between `publicPrefix` and `modulePrefix`?**
|
|
622
656
|
- `publicPrefix`: Removes prefix from interface paths, only affects generated function names
|
|
623
657
|
- Example: `/api/user/list` after removing `/api`, function name becomes `userListGet`
|
|
624
|
-
- `
|
|
658
|
+
- `modulePrefix`: Adds prefix to request paths, affects actual request URLs
|
|
625
659
|
- Example: `/api/user/list` after adding `/forward`, request URL becomes `/forward/api/user/list`
|
|
626
660
|
|
|
627
661
|
5. **How to configure different `dataLevel` for multiple servers?**
|
|
@@ -629,7 +663,7 @@ All methods support type-safe parameter and response type definitions.
|
|
|
629
663
|
```json
|
|
630
664
|
{
|
|
631
665
|
"dataLevel": "serve",
|
|
632
|
-
"
|
|
666
|
+
"swaggerConfig": [
|
|
633
667
|
{
|
|
634
668
|
"url": "http://old-api.com/swagger.json",
|
|
635
669
|
"dataLevel": "axios",
|
|
@@ -646,11 +680,41 @@ All methods support type-safe parameter and response type definitions.
|
|
|
646
680
|
- `old-api.ts` uses `dataLevel: "axios"`
|
|
647
681
|
- `new-api.ts` uses the global `dataLevel: "serve"`
|
|
648
682
|
|
|
649
|
-
6. **How to
|
|
683
|
+
6. **How to configure different `dataLevel` for individual interfaces?**
|
|
684
|
+
|
|
685
|
+
```json
|
|
686
|
+
{
|
|
687
|
+
"dataLevel": "serve",
|
|
688
|
+
"swaggerConfig": [
|
|
689
|
+
{
|
|
690
|
+
"url": "http://api.com/swagger.json",
|
|
691
|
+
"apiListFileName": "api.ts",
|
|
692
|
+
"dataLevel": "data",
|
|
693
|
+
"includeInterface": [
|
|
694
|
+
{
|
|
695
|
+
"path": "/api/user/detail",
|
|
696
|
+
"method": "get",
|
|
697
|
+
"dataLevel": "axios"
|
|
698
|
+
},
|
|
699
|
+
{
|
|
700
|
+
"path": "/api/user/list",
|
|
701
|
+
"method": "get"
|
|
702
|
+
}
|
|
703
|
+
]
|
|
704
|
+
}
|
|
705
|
+
]
|
|
706
|
+
}
|
|
707
|
+
```
|
|
708
|
+
|
|
709
|
+
- `/api/user/detail` uses interface-level `dataLevel: "axios"` (highest priority)
|
|
710
|
+
- `/api/user/list` uses server-level `dataLevel: "data"`
|
|
711
|
+
- Other server interfaces use global `dataLevel: "serve"`
|
|
712
|
+
|
|
713
|
+
7. **How to generate only specific interfaces?**
|
|
650
714
|
- Use `includeInterface` configuration:
|
|
651
715
|
```json
|
|
652
716
|
{
|
|
653
|
-
"
|
|
717
|
+
"swaggerConfig": [
|
|
654
718
|
{
|
|
655
719
|
"url": "http://api.com/swagger.json",
|
|
656
720
|
"includeInterface": [
|
|
@@ -663,7 +727,7 @@ All methods support type-safe parameter and response type definitions.
|
|
|
663
727
|
```
|
|
664
728
|
- Or use `excludeInterface` to exclude unwanted interfaces
|
|
665
729
|
|
|
666
|
-
|
|
730
|
+
8. **What if generated files are overwritten?**
|
|
667
731
|
- Files like `config.ts`, `error-message.ts`, `fetch.ts`, `api-type.d.ts` are only generated when they don't exist
|
|
668
732
|
- API list files and type files are regenerated each time
|
|
669
733
|
- It's recommended to add generated files to version control for easy tracking of changes
|