fork of hey-api/openapi-ts because I need some additional things
docs: add parser.transforms.schemas configuration documentation
Co-authored-by: mrlubos <12529395+mrlubos@users.noreply.github.com>
+68
+68
docs/openapi-ts/configuration/parser.md
+68
docs/openapi-ts/configuration/parser.md
···
447
447
448
448
You can customize the naming and casing pattern for `requests` and `responses` schemas using the `.name` and `.case` options.
449
449
450
+
### Schemas
451
+
452
+
Sometimes your schema names are auto-generated or follow a naming convention that produces verbose or awkward type names. The `schemas` transform allows you to rename schema component keys throughout the specification, automatically updating all `$ref` pointers.
453
+
454
+
This is useful for:
455
+
456
+
- Stripping version markers from schema names
457
+
- Removing vendor prefixes
458
+
- Converting naming conventions
459
+
- Shortening deeply qualified names
460
+
461
+
::: code-group
462
+
463
+
```js [function]
464
+
export default {
465
+
input: 'hey-api/backend', // sign up at app.heyapi.dev
466
+
output: 'src/client',
467
+
parser: {
468
+
transforms: {
469
+
schemas: {
470
+
name: (name) => {
471
+
// Strip version markers: ServiceRoot_v1_20_0_ServiceRoot → ServiceRoot
472
+
let clean = name.replace(/([A-Za-z\d]+)_v\d+_\d+_\d+_([A-Za-z\d]*)/g, (_, p1, p2) =>
473
+
p2.startsWith(p1) ? p2 : p1 + p2,
474
+
);
475
+
// Deduplicate prefixes: Foo_Foo → Foo
476
+
const m = clean.match(/^([A-Za-z\d]+)_\1([A-Za-z\d]*)$/);
477
+
if (m) clean = m[1] + m[2];
478
+
return clean;
479
+
},
480
+
},
481
+
},
482
+
},
483
+
};
484
+
```
485
+
486
+
```js [template]
487
+
export default {
488
+
input: 'hey-api/backend', // sign up at app.heyapi.dev
489
+
output: 'src/client',
490
+
parser: {
491
+
transforms: {
492
+
schemas: {
493
+
name: 'Api{{name}}', // Add "Api" prefix to all schemas
494
+
},
495
+
},
496
+
},
497
+
};
498
+
```
499
+
500
+
```js [disabled]
501
+
export default {
502
+
input: 'hey-api/backend', // sign up at app.heyapi.dev
503
+
output: 'src/client',
504
+
parser: {
505
+
transforms: {
506
+
schemas: false, // [!code ++]
507
+
},
508
+
},
509
+
};
510
+
```
511
+
512
+
:::
513
+
514
+
::: tip Name Collisions
515
+
If a transformed schema name conflicts with an existing schema, the rename is skipped for that schema to prevent overwrites. The original name is preserved.
516
+
:::
517
+
450
518
## Pagination
451
519
452
520
Paginated operations are detected by having a pagination keyword in its parameters or request body. By default, we consider the following to be pagination keywords: `after`, `before`, `cursor`, `offset`, `page`, and `start`.