anl 26.106.1 → 26.107.0
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 +300 -37
- package/README.es.md +299 -36
- package/README.fr.md +354 -36
- package/README.jp.md +246 -15
- package/README.md +262 -29
- package/README.ru.md +246 -15
- package/README.zh.md +289 -50
- package/lib/package.json.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
|
@@ -176,30 +176,41 @@ $ anl type
|
|
|
176
176
|
|
|
177
177
|
#### Configuration Item Descriptions
|
|
178
178
|
|
|
179
|
-
| Configuration Item
|
|
180
|
-
|
|
|
181
|
-
| saveTypeFolderPath
|
|
182
|
-
| saveApiListFolderPath
|
|
183
|
-
| saveEnumFolderPath
|
|
184
|
-
| importEnumPath
|
|
185
|
-
| swaggerJsonUrl
|
|
186
|
-
| swaggerServers
|
|
187
|
-
| swaggerServers[].url
|
|
188
|
-
| swaggerServers[].publicPrefix
|
|
189
|
-
| swaggerServers[].apiListFileName
|
|
190
|
-
| swaggerServers[].headers
|
|
191
|
-
|
|
|
192
|
-
| dataLevel
|
|
193
|
-
|
|
|
194
|
-
|
|
|
195
|
-
|
|
|
196
|
-
|
|
|
197
|
-
|
|
|
198
|
-
|
|
|
199
|
-
|
|
|
200
|
-
|
|
|
201
|
-
|
|
|
202
|
-
|
|
|
179
|
+
| Configuration Item | Type | Required | Description |
|
|
180
|
+
| ----------------------------------- | ------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
181
|
+
| saveTypeFolderPath | string | Yes | Type definition file save path |
|
|
182
|
+
| saveApiListFolderPath | string | Yes | API request function file save path |
|
|
183
|
+
| saveEnumFolderPath | string | Yes | Enum data file save path |
|
|
184
|
+
| importEnumPath | string | Yes | Enum import path (path referenced by enum files in apps/types/models/\*.ts) |
|
|
185
|
+
| swaggerJsonUrl | string | No | Swagger JSON documentation address (migrated to `swaggerServers`, retained for backward compatibility) **This field will be removed in future versions** |
|
|
186
|
+
| swaggerServers | object \| Array<object> | No | Swagger server configuration. Single server can be an object, multiple servers use an array. Each server can configure `url`, `publicPrefix`, `pathPrefix`, `apiListFileName`, `headers`, `dataLevel`, `parameterSeparator`, `includeInterface`, `excludeInterface`<br />See single and multiple Swagger server configuration examples above |
|
|
187
|
+
| swaggerServers[].url | string | Yes | Swagger JSON documentation address |
|
|
188
|
+
| swaggerServers[].publicPrefix | string | No | Common prefix on url path, e.g.: api/users, api/users/{id}, api is the common prefix |
|
|
189
|
+
| swaggerServers[].apiListFileName | string | No | API list file name, defaults to `index.ts`. When using multiple servers, each server's file name must be unique |
|
|
190
|
+
| swaggerServers[].headers | object | No | Request header configuration for this server |
|
|
191
|
+
| swaggerServers[].pathPrefix | 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 `pathPrefix: "/forward"`<br />`/publicPrefix/pathPrefix/user` becomes `/api/forward/user` |
|
|
192
|
+
| swaggerServers[].dataLevel | 'data' \| 'serve' \| 'axios' | No | Interface return data level for this server. If not set, uses global `dataLevel` configuration |
|
|
193
|
+
| swaggerServers[].parameterSeparator | '$' \| '\_' | No | Separator used when generating API names and type names for this server. If not set, uses global `parameterSeparator` configuration |
|
|
194
|
+
| swaggerServers[].includeInterface | Array<{path: string, method: string}> | No | List of interfaces to include for this server. If not set, uses global `includeInterface` configuration |
|
|
195
|
+
| swaggerServers[].excludeInterface | Array<{path: string, method: string}> | No | List of interfaces to exclude for this server. If not set, uses global `excludeInterface` configuration |
|
|
196
|
+
| requestMethodsImportPath | string | Yes | Request method import path |
|
|
197
|
+
| dataLevel | 'data' \| 'serve' \| 'axios' | No | Global interface return data level configuration, default: `'serve'`. Each server can override individually |
|
|
198
|
+
| formatting | object | No | Code formatting configuration |
|
|
199
|
+
| formatting.indentation | string | No | Code indentation character, e.g.: `"\t"` or `" "` (two spaces) |
|
|
200
|
+
| formatting.lineEnding | string | No | Line ending, e.g.: `"\n"` (LF) or `"\r\n"` (CRLF) |
|
|
201
|
+
| headers | object | No | Request header configuration (migrated to `swaggerServers`, retained for backward compatibility) |
|
|
202
|
+
| includeInterface | Array<{path: string, method: string}> | No | Global included interfaces: The interface list file specified by `saveApiListFolderPath` will only include interfaces in the list, mutually exclusive with `excludeInterface` field. Each server can override individually |
|
|
203
|
+
| 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 |
|
|
204
|
+
| publicPrefix | string | No | Global common prefix on url path (migrated to `swaggerServers`, retained for backward compatibility) |
|
|
205
|
+
| pathPrefix | string | No | Global request path prefix (each server can override individually) |
|
|
206
|
+
| apiListFileName | string | No | Global API list file name, defaults to `index.ts` (migrated to `swaggerServers`, retained for backward compatibility) |
|
|
207
|
+
| enmuConfig | object | Yes | Enum configuration object |
|
|
208
|
+
| enmuConfig.erasableSyntaxOnly | boolean | Yes | Align with tsconfig.json `compilerOptions.erasableSyntaxOnly`. When `true`, generates const objects instead of enums (type-only syntax). Default: `false` |
|
|
209
|
+
| enmuConfig.varnames | string | No | Swagger schema field name for custom enum member names. Default: `enum-varnames`. |
|
|
210
|
+
| enmuConfig.comment | string | No | Swagger schema field name for custom enum descriptions (used for generating comments). Default: `enum-descriptions`. |
|
|
211
|
+
| 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 |
|
|
212
|
+
| enmuConfig.varnames | string | No | Schema field name that stores custom enum member identifiers. Default: `enum-varnames`. |
|
|
213
|
+
| enmuConfig.comment | string | No | Schema field name that stores enum member descriptions (used for inline comments). Default: `enum-descriptions`. |
|
|
203
214
|
|
|
204
215
|
#### Configuration Items and Generated Files Correspondence
|
|
205
216
|
|
|
@@ -253,6 +264,48 @@ export const userDetailGet = (params: UserDetail_GET.Query) => GET<UserDetail_GE
|
|
|
253
264
|
|
|
254
265
|
### Feature Descriptions
|
|
255
266
|
|
|
267
|
+
#### Configuration Priority
|
|
268
|
+
|
|
269
|
+
The tool supports global configuration and server-level configuration, following these priority rules:
|
|
270
|
+
|
|
271
|
+
**Priority: Server-level configuration > Global configuration > Default values**
|
|
272
|
+
|
|
273
|
+
The following configuration items support server-level override of global configuration:
|
|
274
|
+
|
|
275
|
+
- `dataLevel`: Interface return data level
|
|
276
|
+
- `parameterSeparator`: Separator for API names and type names
|
|
277
|
+
- `includeInterface`: List of included interfaces
|
|
278
|
+
- `excludeInterface`: List of excluded interfaces
|
|
279
|
+
- `pathPrefix`: Request path prefix
|
|
280
|
+
- `publicPrefix`: URL common prefix
|
|
281
|
+
- `headers`: Request header configuration
|
|
282
|
+
|
|
283
|
+
**Example:**
|
|
284
|
+
|
|
285
|
+
```json
|
|
286
|
+
{
|
|
287
|
+
"dataLevel": "serve",
|
|
288
|
+
"parameterSeparator": "_",
|
|
289
|
+
"swaggerServers": [
|
|
290
|
+
{
|
|
291
|
+
"url": "http://api1.example.com/swagger.json",
|
|
292
|
+
"dataLevel": "data",
|
|
293
|
+
"apiListFileName": "api1.ts"
|
|
294
|
+
},
|
|
295
|
+
{
|
|
296
|
+
"url": "http://api2.example.com/swagger.json",
|
|
297
|
+
"apiListFileName": "api2.ts"
|
|
298
|
+
}
|
|
299
|
+
]
|
|
300
|
+
}
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
In the above configuration:
|
|
304
|
+
|
|
305
|
+
- `api1.ts` uses `dataLevel: "data"` (server-level configuration)
|
|
306
|
+
- `api2.ts` uses `dataLevel: "serve"` (global configuration)
|
|
307
|
+
- Both servers use `parameterSeparator: "_"` (global configuration)
|
|
308
|
+
|
|
256
309
|
#### Type Parsing
|
|
257
310
|
|
|
258
311
|
- Supports all OpenAPI 3.0 specification data types
|
|
@@ -303,6 +356,73 @@ interface User {
|
|
|
303
356
|
}
|
|
304
357
|
```
|
|
305
358
|
|
|
359
|
+
#### Data Level Configuration (dataLevel)
|
|
360
|
+
|
|
361
|
+
`dataLevel` is used to configure the extraction level of interface return data, supporting three options:
|
|
362
|
+
|
|
363
|
+
1. **`'serve'` (default)**: Extracts the `data` field from server response
|
|
364
|
+
|
|
365
|
+
```typescript
|
|
366
|
+
// Server returns: { code: 200, message: 'success', data: { id: 1, name: 'user' } }
|
|
367
|
+
// Function returns: { id: 1, name: 'user' }
|
|
368
|
+
```
|
|
369
|
+
|
|
370
|
+
2. **`'data'`**: Extracts the `data.data` field (for nested data scenarios)
|
|
371
|
+
|
|
372
|
+
```typescript
|
|
373
|
+
// Server returns: { data: { code: 200, data: { id: 1, name: 'user' } } }
|
|
374
|
+
// Function returns: { id: 1, name: 'user' }
|
|
375
|
+
```
|
|
376
|
+
|
|
377
|
+
3. **`'axios'`**: Returns the complete axios response object
|
|
378
|
+
```typescript
|
|
379
|
+
// Server returns: { code: 200, message: 'success', data: { id: 1, name: 'user' } }
|
|
380
|
+
// Function returns: { code: 200, message: 'success', data: { id: 1, name: 'user' } }
|
|
381
|
+
```
|
|
382
|
+
|
|
383
|
+
**Configuration example:**
|
|
384
|
+
|
|
385
|
+
```json
|
|
386
|
+
{
|
|
387
|
+
"dataLevel": "serve",
|
|
388
|
+
"swaggerServers": [
|
|
389
|
+
{
|
|
390
|
+
"url": "http://api1.example.com/swagger.json",
|
|
391
|
+
"dataLevel": "data"
|
|
392
|
+
}
|
|
393
|
+
]
|
|
394
|
+
}
|
|
395
|
+
```
|
|
396
|
+
|
|
397
|
+
> **Note**: Server-level `dataLevel` configuration will override global configuration.
|
|
398
|
+
|
|
399
|
+
#### Code Formatting
|
|
400
|
+
|
|
401
|
+
The tool supports custom code formatting options, controlled by the `formatting` configuration:
|
|
402
|
+
|
|
403
|
+
**Configuration example:**
|
|
404
|
+
|
|
405
|
+
```json
|
|
406
|
+
{
|
|
407
|
+
"formatting": {
|
|
408
|
+
"indentation": "\t",
|
|
409
|
+
"lineEnding": "\n"
|
|
410
|
+
}
|
|
411
|
+
}
|
|
412
|
+
```
|
|
413
|
+
|
|
414
|
+
**Configuration description:**
|
|
415
|
+
|
|
416
|
+
- `indentation`: Code indentation character
|
|
417
|
+
- `"\t"`: Use Tab indentation (default)
|
|
418
|
+
- `" "`: Use 2 spaces indentation
|
|
419
|
+
- `" "`: Use 4 spaces indentation
|
|
420
|
+
- `lineEnding`: Line ending type
|
|
421
|
+
- `"\n"`: LF (Linux/macOS style, recommended)
|
|
422
|
+
- `"\r\n"`: CRLF (Windows style)
|
|
423
|
+
|
|
424
|
+
**Note:** If Prettier is configured in the project, the generated code will automatically use Prettier for formatting, and the `formatting` configuration may be overridden by Prettier.
|
|
425
|
+
|
|
306
426
|
#### File Upload
|
|
307
427
|
|
|
308
428
|
When file upload types are detected, corresponding request headers are automatically added:
|
|
@@ -370,6 +490,51 @@ The tool supports configuring multiple Swagger servers, each server can be confi
|
|
|
370
490
|
- Subsequent servers' APIs will be appended to their respective `apiListFileName` files
|
|
371
491
|
- Type definitions and enums will be merged into a unified folder to avoid duplication
|
|
372
492
|
|
|
493
|
+
**Server-level configuration:**
|
|
494
|
+
|
|
495
|
+
Each server supports independent configuration of the following options. If not set, global configuration will be used:
|
|
496
|
+
|
|
497
|
+
- `dataLevel` - Interface return data level
|
|
498
|
+
- `parameterSeparator` - Separator for API names and type names
|
|
499
|
+
- `includeInterface` - List of included interfaces
|
|
500
|
+
- `excludeInterface` - List of excluded interfaces
|
|
501
|
+
- `pathPrefix` - Request path prefix
|
|
502
|
+
|
|
503
|
+
#### Path Prefix (pathPrefix)
|
|
504
|
+
|
|
505
|
+
`pathPrefix` is used to automatically add a prefix to all API request paths, which is particularly useful in the following scenarios:
|
|
506
|
+
|
|
507
|
+
1. **Reverse proxy scenarios**: When backend services are forwarded through a reverse proxy
|
|
508
|
+
2. **API Gateway**: Uniformly add gateway prefix to paths
|
|
509
|
+
3. **Multi-environment configuration**: Use different path prefixes for different environments
|
|
510
|
+
|
|
511
|
+
**Usage example:**
|
|
512
|
+
|
|
513
|
+
```json
|
|
514
|
+
{
|
|
515
|
+
"swaggerServers": [
|
|
516
|
+
{
|
|
517
|
+
"url": "http://api.example.com/swagger.json",
|
|
518
|
+
"pathPrefix": "/forward",
|
|
519
|
+
"apiListFileName": "api.ts"
|
|
520
|
+
}
|
|
521
|
+
]
|
|
522
|
+
}
|
|
523
|
+
```
|
|
524
|
+
|
|
525
|
+
**Effect:**
|
|
526
|
+
|
|
527
|
+
The path `/api/user/list` defined in Swagger will be generated as:
|
|
528
|
+
|
|
529
|
+
```typescript
|
|
530
|
+
export const apiUserListGet = (params: ApiUserList_GET.Query) => GET<ApiUserList_GET.Response>('/forward/api/user/list', params);
|
|
531
|
+
```
|
|
532
|
+
|
|
533
|
+
**Difference from publicPrefix:**
|
|
534
|
+
|
|
535
|
+
- `publicPrefix`: Used to remove common prefix from interface paths (only affects generated function names)
|
|
536
|
+
- `pathPrefix`: Used to add prefix to actual request paths (affects runtime request URLs)
|
|
537
|
+
|
|
373
538
|
**Configuration example:**
|
|
374
539
|
|
|
375
540
|
```json
|
|
@@ -379,14 +544,24 @@ The tool supports configuring multiple Swagger servers, each server can be confi
|
|
|
379
544
|
"url": "http://api1.example.com/swagger.json",
|
|
380
545
|
"apiListFileName": "api1.ts",
|
|
381
546
|
"publicPrefix": "/api/v1",
|
|
547
|
+
"pathPrefix": "/forward",
|
|
548
|
+
"dataLevel": "serve",
|
|
549
|
+
"parameterSeparator": "_",
|
|
382
550
|
"headers": {
|
|
383
551
|
"Authorization": "Bearer token1"
|
|
384
|
-
}
|
|
552
|
+
},
|
|
553
|
+
"includeInterface": [
|
|
554
|
+
{
|
|
555
|
+
"path": "/api/v1/users",
|
|
556
|
+
"method": "get"
|
|
557
|
+
}
|
|
558
|
+
]
|
|
385
559
|
},
|
|
386
560
|
{
|
|
387
561
|
"url": "http://api2.example.com/swagger.json",
|
|
388
562
|
"apiListFileName": "api2.ts",
|
|
389
563
|
"publicPrefix": "/api/v2",
|
|
564
|
+
"dataLevel": "data",
|
|
390
565
|
"headers": {
|
|
391
566
|
"Authorization": "Bearer token2"
|
|
392
567
|
}
|
|
@@ -420,21 +595,79 @@ All methods support type-safe parameter and response type definitions.
|
|
|
420
595
|
|
|
421
596
|
1. Ensure the Swagger JSON documentation address is accessible
|
|
422
597
|
2. Paths in the configuration file need to be relative to the project root directory
|
|
423
|
-
3. Generated files will overwrite existing files with the same name
|
|
598
|
+
3. Generated files will overwrite existing files with the same name (but `config.ts`, `error-message.ts`, `fetch.ts`, `api-type.d.ts` will not be overwritten if they already exist)
|
|
424
599
|
4. It's recommended to add generated files to version control
|
|
425
600
|
5. When using multiple Swagger servers, ensure each server's `apiListFileName` is unique to avoid file overwriting
|
|
426
601
|
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`, `pathPrefix`) will override global configuration
|
|
603
|
+
8. `includeInterface` and `excludeInterface` cannot be configured simultaneously. If both are configured, `includeInterface` will be prioritized
|
|
427
604
|
|
|
428
605
|
### Common Issues
|
|
429
606
|
|
|
430
|
-
1. Generated type file formatting fails
|
|
607
|
+
1. **Generated type file formatting fails**
|
|
431
608
|
- Check if prettier is installed
|
|
432
609
|
- Confirm if there's a prettier configuration file in the project root directory
|
|
610
|
+
- Check if the `formatting` configuration is correct
|
|
433
611
|
|
|
434
|
-
2. Request function import path error
|
|
435
|
-
- Check if the requestMethodsImportPath configuration is correct
|
|
612
|
+
2. **Request function import path error**
|
|
613
|
+
- Check if the `requestMethodsImportPath` configuration is correct
|
|
436
614
|
- Confirm if the request method file exists
|
|
437
615
|
|
|
616
|
+
3. **When to use `pathPrefix`?**
|
|
617
|
+
- When your APIs need to be accessed through a reverse proxy or gateway
|
|
618
|
+
- For example: Swagger defines `/api/user`, but the actual request needs to be `/gateway/api/user`
|
|
619
|
+
- Set `pathPrefix: "/gateway"` to achieve this
|
|
620
|
+
|
|
621
|
+
4. **What's the difference between `publicPrefix` and `pathPrefix`?**
|
|
622
|
+
- `publicPrefix`: Removes prefix from interface paths, only affects generated function names
|
|
623
|
+
- Example: `/api/user/list` after removing `/api`, function name becomes `userListGet`
|
|
624
|
+
- `pathPrefix`: Adds prefix to request paths, affects actual request URLs
|
|
625
|
+
- Example: `/api/user/list` after adding `/forward`, request URL becomes `/forward/api/user/list`
|
|
626
|
+
|
|
627
|
+
5. **How to configure different `dataLevel` for multiple servers?**
|
|
628
|
+
|
|
629
|
+
```json
|
|
630
|
+
{
|
|
631
|
+
"dataLevel": "serve",
|
|
632
|
+
"swaggerServers": [
|
|
633
|
+
{
|
|
634
|
+
"url": "http://old-api.com/swagger.json",
|
|
635
|
+
"dataLevel": "axios",
|
|
636
|
+
"apiListFileName": "old-api.ts"
|
|
637
|
+
},
|
|
638
|
+
{
|
|
639
|
+
"url": "http://new-api.com/swagger.json",
|
|
640
|
+
"apiListFileName": "new-api.ts"
|
|
641
|
+
}
|
|
642
|
+
]
|
|
643
|
+
}
|
|
644
|
+
```
|
|
645
|
+
|
|
646
|
+
- `old-api.ts` uses `dataLevel: "axios"`
|
|
647
|
+
- `new-api.ts` uses the global `dataLevel: "serve"`
|
|
648
|
+
|
|
649
|
+
6. **How to generate only specific interfaces?**
|
|
650
|
+
- Use `includeInterface` configuration:
|
|
651
|
+
```json
|
|
652
|
+
{
|
|
653
|
+
"swaggerServers": [
|
|
654
|
+
{
|
|
655
|
+
"url": "http://api.com/swagger.json",
|
|
656
|
+
"includeInterface": [
|
|
657
|
+
{ "path": "/api/user", "method": "get" },
|
|
658
|
+
{ "path": "/api/user/{id}", "method": "post" }
|
|
659
|
+
]
|
|
660
|
+
}
|
|
661
|
+
]
|
|
662
|
+
}
|
|
663
|
+
```
|
|
664
|
+
- Or use `excludeInterface` to exclude unwanted interfaces
|
|
665
|
+
|
|
666
|
+
7. **What if generated files are overwritten?**
|
|
667
|
+
- Files like `config.ts`, `error-message.ts`, `fetch.ts`, `api-type.d.ts` are only generated when they don't exist
|
|
668
|
+
- API list files and type files are regenerated each time
|
|
669
|
+
- It's recommended to add generated files to version control for easy tracking of changes
|
|
670
|
+
|
|
438
671
|
# `anl lint` Command Usage
|
|
439
672
|
|
|
440
673
|
> Provides **interactive multi-select** configuration for various lint tools in frontend projects, including:
|