camunda-schema-bundler 2.4.6 → 2.4.8
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 +7 -3
- package/dist/bundle.d.ts +11 -0
- package/dist/bundle.d.ts.map +1 -1
- package/dist/bundle.js +373 -28
- package/dist/bundle.js.map +1 -1
- package/dist/cli.js +13 -0
- package/dist/cli.js.map +1 -1
- package/dist/fetch-and-bundle.d.ts.map +1 -1
- package/dist/fetch-and-bundle.js +1 -0
- package/dist/fetch-and-bundle.js.map +1 -1
- package/dist/helpers.d.ts +57 -0
- package/dist/helpers.d.ts.map +1 -1
- package/dist/helpers.js +125 -0
- package/dist/helpers.js.map +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/types.d.ts +11 -0
- package/dist/types.d.ts.map +1 -1
- package/package.json +5 -4
package/README.md
CHANGED
|
@@ -109,6 +109,7 @@ camunda-schema-bundler --version
|
|
|
109
109
|
| `--deref-path-local` | Inline remaining path-local `$ref`s (needed for Microsoft.OpenApi) |
|
|
110
110
|
| `--allow-like-refs` | Don't fail on surviving path-local `$like` refs |
|
|
111
111
|
| `--allow-param-refs` | Don't fail on surviving path-local `$ref`s inside `parameters` arrays |
|
|
112
|
+
| `--allow-response-refs` | Don't fail on surviving path-local `$ref`s used as `responses` map values |
|
|
112
113
|
| `--allow-interior-refs` | Don't fail on `$ref`s that point inside a component schema (e.g. `#/components/schemas/Foo/allOf/0`) and cannot be retargeted to a named component |
|
|
113
114
|
| **General** | |
|
|
114
115
|
| `--help`, `-h` | Show help |
|
|
@@ -195,6 +196,8 @@ import {
|
|
|
195
196
|
findPathLocalLikeRefs, // Find surviving path-local $like refs in a spec
|
|
196
197
|
findPathLocalParameterRefs, // Find surviving path-local $refs in parameters arrays
|
|
197
198
|
forEachParameterArray, // Visit every path-item / operation `parameters` array
|
|
199
|
+
findPathLocalResponseRefs, // Find surviving path-local $refs in responses maps
|
|
200
|
+
forEachResponsesMap, // Visit every operation `responses` map
|
|
198
201
|
} from 'camunda-schema-bundler';
|
|
199
202
|
```
|
|
200
203
|
|
|
@@ -214,9 +217,10 @@ import {
|
|
|
214
217
|
7. **Retarget interior refs** — Rewrite `$ref`s that point inside a component schema (e.g. `#/components/schemas/AuthenticatedCamundaUserResult/allOf/0`) to the named component they resolve to. `SwaggerParser.bundle()` emits these when a schema is first met nested inside another component; once fresh dedup turns the nested copy into a component ref, they are refs to refs that generators cannot follow. Fail-fast if any cannot be retargeted (configurable with `--allow-interior-refs`)
|
|
215
218
|
8. **Rewrite** — Decode URI-encoded internal refs (`%24like` → `$like`)
|
|
216
219
|
9. **Inline parameter refs** — Always inline path-local `$ref`s that survive inside `parameters` arrays. `SwaggerParser.bundle()` drops `components.parameters` entirely and dedupes the resulting identical parameter objects into `#/paths/...` refs, which step 4 cannot rewrite because there is no surviving component to point at. Generators cannot resolve them (openapi-generator aborts with "There are duplicate parameter values"), and parameters are never emitted as named types, so inlining is lossless. Fail-fast if any survive (configurable with `--allow-param-refs`)
|
|
217
|
-
10. **
|
|
218
|
-
11. **
|
|
219
|
-
12. **
|
|
220
|
+
10. **Inline response refs** — Same for path-local `$ref`s used as `responses` map values: `components.responses` does not survive bundling either, so every reuse of a shared response (e.g. `401`/`500` error responses) becomes a `#/paths/.../responses/<status>` ref. Consumers that only resolve `#/components/...` pointers drop these. Response Objects are never emitted as named types (the schemas inside them keep their component refs), so inlining is lossless. Only targets that are Response Objects are inlined; fail-fast if any survive (configurable with `--allow-response-refs`)
|
|
221
|
+
11. **Validate** — Fail-fast if any path-local `$like` refs survive (configurable with `--allow-like-refs`)
|
|
222
|
+
12. **Dereference** (optional, `--deref-path-local`) — Inline remaining path-local `$ref`s for strict generators
|
|
223
|
+
13. **Extract metadata** — Build the intermediate representation (semantic keys, unions, operations, etc.)
|
|
220
224
|
|
|
221
225
|
## Metadata IR
|
|
222
226
|
|
package/dist/bundle.d.ts
CHANGED
|
@@ -1,4 +1,15 @@
|
|
|
1
1
|
import type { BundleOptions, BundleResult } from './types.js';
|
|
2
|
+
/**
|
|
3
|
+
* Collapse `$ref`s that point into a component subtree (see Step 4d).
|
|
4
|
+
* Rewrites in place and returns the number of collapsed refs plus the refs
|
|
5
|
+
* that survive: subtree refs that do not resolve, through bare `$ref` hops,
|
|
6
|
+
* to an existing named top-level component. The caller decides whether
|
|
7
|
+
* survivors are fatal (see `allowComponentInteriorRefs`).
|
|
8
|
+
*/
|
|
9
|
+
export declare function collapseComponentSubtreeRefs(doc: Record<string, unknown>): {
|
|
10
|
+
collapsed: number;
|
|
11
|
+
survivors: string[];
|
|
12
|
+
};
|
|
2
13
|
/**
|
|
3
14
|
* Bundle the multi-file OpenAPI spec into a single normalized JSON document.
|
|
4
15
|
*/
|
package/dist/bundle.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../src/bundle.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../src/bundle.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAe,MAAM,YAAY,CAAC;AA2qB3E;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAC1E,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB,CAsIA;AAED;;GAEG;AACH,wBAAsB,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CA41B1E"}
|
package/dist/bundle.js
CHANGED
|
@@ -8,7 +8,7 @@ import fs from 'node:fs';
|
|
|
8
8
|
import path from 'node:path';
|
|
9
9
|
import SwaggerParser from '@apidevtools/swagger-parser';
|
|
10
10
|
import { parse as parseYaml } from 'yaml';
|
|
11
|
-
import { listFilesRecursive, hashDirectoryTree, normalizeInternalRef, rewriteInternalRefs, rewriteExternalRefsToLocal, resolveInternalRef, canonicalStringify, structuralStringify, findPathLocalLikeRefs, forEachParameterArray, findPathLocalParameterRefs, sortRequiredArrays, collapseComponentInteriorRefs, } from './helpers.js';
|
|
11
|
+
import { listFilesRecursive, hashDirectoryTree, normalizeInternalRef, rewriteInternalRefs, rewriteExternalRefsToLocal, resolveInternalRef, resolveTerminalRef, canonicalStringify, structuralStringify, findPathLocalLikeRefs, forEachParameterArray, findPathLocalParameterRefs, forEachResponsesMap, findPathLocalResponseRefs, sortRequiredArrays, collapseComponentInteriorRefs, } from './helpers.js';
|
|
12
12
|
import { extractMetadata } from './metadata.js';
|
|
13
13
|
/**
|
|
14
14
|
* Promote inline schemas inside component-level `oneOf`/`anyOf` compositions
|
|
@@ -572,6 +572,138 @@ function isMonolithicEntryFile(entryPath) {
|
|
|
572
572
|
return false;
|
|
573
573
|
}
|
|
574
574
|
}
|
|
575
|
+
/**
|
|
576
|
+
* Collapse `$ref`s that point into a component subtree (see Step 4d).
|
|
577
|
+
* Rewrites in place and returns the number of collapsed refs plus the refs
|
|
578
|
+
* that survive: subtree refs that do not resolve, through bare `$ref` hops,
|
|
579
|
+
* to an existing named top-level component. The caller decides whether
|
|
580
|
+
* survivors are fatal (see `allowComponentInteriorRefs`).
|
|
581
|
+
*/
|
|
582
|
+
export function collapseComponentSubtreeRefs(doc) {
|
|
583
|
+
let collapsed = 0;
|
|
584
|
+
const isComponentSubtreeRef = (ref) => /^#\/components\/[^/]+\/[^/]+\/./.test(ref);
|
|
585
|
+
const bareRefTarget = (ref) => {
|
|
586
|
+
const target = resolveInternalRef(doc, ref);
|
|
587
|
+
if (!target || typeof target !== 'object' || Array.isArray(target))
|
|
588
|
+
return undefined;
|
|
589
|
+
const keys = Object.keys(target);
|
|
590
|
+
const next = target['$ref'];
|
|
591
|
+
return keys.length === 1 && typeof next === 'string' ? next : undefined;
|
|
592
|
+
};
|
|
593
|
+
// Keys whose values are literal payloads (data, not OpenAPI/schema
|
|
594
|
+
// positions): a `$ref` property inside them is data and must not be touched.
|
|
595
|
+
const LITERAL_KEYS = new Set(['example', 'default', 'enum', 'const']);
|
|
596
|
+
const isLiteralKey = (k) => LITERAL_KEYS.has(k) || k.startsWith('x-');
|
|
597
|
+
const survivors = [];
|
|
598
|
+
const seen = new Set();
|
|
599
|
+
// Keys (in `node` context) whose value is a map of user-chosen names.
|
|
600
|
+
const NAME_MAP_KEYS = new Set([
|
|
601
|
+
'properties',
|
|
602
|
+
'patternProperties',
|
|
603
|
+
'$defs',
|
|
604
|
+
'definitions',
|
|
605
|
+
'dependentSchemas',
|
|
606
|
+
'content',
|
|
607
|
+
'headers',
|
|
608
|
+
'encoding',
|
|
609
|
+
]);
|
|
610
|
+
// Keys whose value is a name map that also admits `x-*` extensions.
|
|
611
|
+
const NAME_MAP_EXT_KEYS = new Set(['responses', 'paths', 'webhooks', 'callbacks']);
|
|
612
|
+
const childCtx = (k, v) => {
|
|
613
|
+
if (k === 'examples')
|
|
614
|
+
return Array.isArray(v) ? undefined : 'exampleMap';
|
|
615
|
+
if (k === 'links')
|
|
616
|
+
return 'linkMap';
|
|
617
|
+
if (NAME_MAP_KEYS.has(k))
|
|
618
|
+
return 'nameMap';
|
|
619
|
+
if (NAME_MAP_EXT_KEYS.has(k))
|
|
620
|
+
return 'nameMapExt';
|
|
621
|
+
return 'node';
|
|
622
|
+
};
|
|
623
|
+
const stack = [
|
|
624
|
+
{ node: doc, ctx: 'node' },
|
|
625
|
+
];
|
|
626
|
+
while (stack.length) {
|
|
627
|
+
const { node, ctx } = stack.pop();
|
|
628
|
+
if (!node || typeof node !== 'object' || seen.has(node))
|
|
629
|
+
continue;
|
|
630
|
+
seen.add(node);
|
|
631
|
+
if (Array.isArray(node)) {
|
|
632
|
+
for (const v of node)
|
|
633
|
+
stack.push({ node: v, ctx: 'node' });
|
|
634
|
+
continue;
|
|
635
|
+
}
|
|
636
|
+
const obj = node;
|
|
637
|
+
if (ctx === 'nameMap' || ctx === 'nameMapExt' || ctx === 'exampleMap' || ctx === 'linkMap') {
|
|
638
|
+
const entryCtx = ctx === 'exampleMap' ? 'exampleObject' : ctx === 'linkMap' ? 'linkObject' : 'node';
|
|
639
|
+
for (const [k, v] of Object.entries(obj)) {
|
|
640
|
+
if (ctx === 'nameMapExt' && k.startsWith('x-'))
|
|
641
|
+
continue;
|
|
642
|
+
stack.push({ node: v, ctx: entryCtx });
|
|
643
|
+
}
|
|
644
|
+
continue;
|
|
645
|
+
}
|
|
646
|
+
const ref = obj['$ref'];
|
|
647
|
+
if (typeof ref === 'string' && isComponentSubtreeRef(ref)) {
|
|
648
|
+
let resolved = ref;
|
|
649
|
+
const chain = new Set();
|
|
650
|
+
// Follow bare internal refs (including path-local intermediaries such
|
|
651
|
+
// as `#/paths/...`) until a named top-level component is reached, or
|
|
652
|
+
// the chain hits a non-bare/missing target or a cycle.
|
|
653
|
+
const isNamedComponentRef = (r) => /^#\/components\/[^/]+\/[^/]+$/.test(r);
|
|
654
|
+
while (resolved.startsWith('#/') && !isNamedComponentRef(resolved)) {
|
|
655
|
+
if (chain.has(resolved))
|
|
656
|
+
break;
|
|
657
|
+
chain.add(resolved);
|
|
658
|
+
const next = bareRefTarget(resolved);
|
|
659
|
+
if (next === undefined)
|
|
660
|
+
break;
|
|
661
|
+
resolved = next;
|
|
662
|
+
}
|
|
663
|
+
// Accept only a ref to an existing, named top-level component.
|
|
664
|
+
// Leaving the subtree pattern is not enough: the chain could end
|
|
665
|
+
// at e.g. an unnamed `#/paths/...` schema.
|
|
666
|
+
const named = /^#\/components\/([^/]+)\/([^/]+)$/.exec(resolved);
|
|
667
|
+
const components = doc.components;
|
|
668
|
+
const namedTargetExists = named !== null &&
|
|
669
|
+
components?.[named[1]] !== undefined &&
|
|
670
|
+
Object.prototype.hasOwnProperty.call(components[named[1]], named[2].replace(/~1/g, '/').replace(/~0/g, '~'));
|
|
671
|
+
if (!namedTargetExists) {
|
|
672
|
+
survivors.push(ref);
|
|
673
|
+
}
|
|
674
|
+
else {
|
|
675
|
+
obj['$ref'] = resolved;
|
|
676
|
+
collapsed++;
|
|
677
|
+
}
|
|
678
|
+
}
|
|
679
|
+
for (const [k, v] of Object.entries(obj)) {
|
|
680
|
+
if (k === '$ref' || isLiteralKey(k))
|
|
681
|
+
continue;
|
|
682
|
+
if (ctx === 'exampleObject' && k === 'value')
|
|
683
|
+
continue;
|
|
684
|
+
if (ctx === 'linkObject' && (k === 'requestBody' || k === 'parameters'))
|
|
685
|
+
continue;
|
|
686
|
+
if (obj === doc && k === 'components' && v && typeof v === 'object') {
|
|
687
|
+
// Each component type map holds user-named components (any name,
|
|
688
|
+
// including `default` / `x-data`); `x-*` on `components` itself is data.
|
|
689
|
+
for (const [type, map] of Object.entries(v)) {
|
|
690
|
+
if (type.startsWith('x-'))
|
|
691
|
+
continue;
|
|
692
|
+
const mapCtx = type === 'examples' ? 'exampleMap' : type === 'links' ? 'linkMap' : 'nameMap';
|
|
693
|
+
stack.push({ node: map, ctx: mapCtx });
|
|
694
|
+
}
|
|
695
|
+
continue;
|
|
696
|
+
}
|
|
697
|
+
const c = childCtx(k, v);
|
|
698
|
+
if (c !== undefined)
|
|
699
|
+
stack.push({ node: v, ctx: c });
|
|
700
|
+
}
|
|
701
|
+
}
|
|
702
|
+
if (survivors.length > 0) {
|
|
703
|
+
return { collapsed, survivors: [...new Set(survivors)].sort() };
|
|
704
|
+
}
|
|
705
|
+
return { collapsed, survivors: [] };
|
|
706
|
+
}
|
|
575
707
|
/**
|
|
576
708
|
* Bundle the multi-file OpenAPI spec into a single normalized JSON document.
|
|
577
709
|
*/
|
|
@@ -594,7 +726,9 @@ export async function bundle(options) {
|
|
|
594
726
|
ambiguousInlineCount: 0,
|
|
595
727
|
dereferencedPathLocalRefCount: 0,
|
|
596
728
|
pathLocalLikeRefCount: 0,
|
|
729
|
+
componentSubtreeRefsCollapsed: 0,
|
|
597
730
|
inlinedPathLocalParameterCount: 0,
|
|
731
|
+
inlinedPathLocalResponseCount: 0,
|
|
598
732
|
collapsedComponentInteriorRefCount: 0,
|
|
599
733
|
componentInteriorRefCount: 0,
|
|
600
734
|
};
|
|
@@ -874,6 +1008,17 @@ export async function bundle(options) {
|
|
|
874
1008
|
const p = node;
|
|
875
1009
|
return typeof p['name'] === 'string' && typeof p['in'] === 'string';
|
|
876
1010
|
};
|
|
1011
|
+
// A parameter target must live in a `parameters` position
|
|
1012
|
+
// (`#/paths/<path>/<method>/parameters/<i>`, Path-Item-level
|
|
1013
|
+
// `#/paths/<path>/parameters/<i>`, or `#/components/parameters/<name>`).
|
|
1014
|
+
// `<path>` must be an API path (a `/`-prefixed key, JSON-pointer-encoded
|
|
1015
|
+
// as `~1`); any other key under `paths` is an `x-*` extension. This is
|
|
1016
|
+
// the same context distinction Step 3e applies to responses. The method segment must be a real HTTP method:
|
|
1017
|
+
// `x-*` extensions are arbitrary data, and a pointer that merely ENDS in
|
|
1018
|
+
// `/parameters/<i>` (e.g. into an example payload) is not a parameters
|
|
1019
|
+
// position either.
|
|
1020
|
+
const PARAMETER_TARGET_REF = /^#\/(?:components\/parameters\/[^/]+|paths\/~1[^/]*(?:\/(?:get|put|post|delete|options|head|patch|trace))?\/parameters\/\d+)$/;
|
|
1021
|
+
const isParameterTargetRef = (ref) => PARAMETER_TARGET_REF.test(ref);
|
|
877
1022
|
for (let pass = 1; pass <= 20; pass++) {
|
|
878
1023
|
let inlined = 0;
|
|
879
1024
|
forEachParameterArray(bundled, (params) => {
|
|
@@ -884,15 +1029,37 @@ export async function bundle(options) {
|
|
|
884
1029
|
const ref = param['$ref'];
|
|
885
1030
|
// Prefer the post-normalization source (normalized $like refs,
|
|
886
1031
|
// promoted schemas); fall back to pre-normalization if the path was
|
|
887
|
-
// removed during normalization.
|
|
888
|
-
|
|
889
|
-
|
|
1032
|
+
// removed during normalization. Follow terminal hops: the snapshots
|
|
1033
|
+
// predate inlining, so an acyclic chain's target is still the
|
|
1034
|
+
// intermediate reference. Cycle-safe: a cycle resolves to undefined.
|
|
1035
|
+
// The walk only starts from — and only continues through — pointers
|
|
1036
|
+
// that are themselves parameters positions: a chain may otherwise
|
|
1037
|
+
// lead into an `x-*` extension or transit a non-parameter position
|
|
1038
|
+
// to launder a non-parameter target.
|
|
1039
|
+
const hopWalk = isParameterTargetRef(ref)
|
|
1040
|
+
? resolveTerminalRef(postNormSnapshot, preNormSnapshot, resolveInternalRef(postNormSnapshot, ref) ??
|
|
1041
|
+
resolveInternalRef(preNormSnapshot, ref), isParameterTargetRef)
|
|
1042
|
+
: { node: undefined };
|
|
1043
|
+
const resolved = hopWalk.node;
|
|
1044
|
+
const intermediateDescription = hopWalk.description;
|
|
890
1045
|
// Only substitute something that is actually a parameter. Anything
|
|
891
|
-
// else — a primitive, a response object, or
|
|
892
|
-
//
|
|
893
|
-
//
|
|
1046
|
+
// else — a primitive, a response object, or a reference cycle —
|
|
1047
|
+
// leaves the $ref in place so the Step 5 guard reports it,
|
|
1048
|
+
// uncounted.
|
|
894
1049
|
if (isParameterObject(resolved)) {
|
|
895
|
-
|
|
1050
|
+
const copy = JSON.parse(JSON.stringify(resolved));
|
|
1051
|
+
// A Reference Object may carry a `description` sibling overriding
|
|
1052
|
+
// the target's (OpenAPI 3.1; 3.0.x processors apply the same
|
|
1053
|
+
// rule). Inlining must not discard that override: the use-site
|
|
1054
|
+
// reference's own sibling wins, then the nearest intermediate
|
|
1055
|
+
// reference's, then the terminal parameter's. `summary` is NOT
|
|
1056
|
+
// copied — a Parameter Object has no such field, so emitting it
|
|
1057
|
+
// would turn a valid reference into invalid output.
|
|
1058
|
+
const override = param['description'] ??
|
|
1059
|
+
intermediateDescription;
|
|
1060
|
+
if (typeof override === 'string')
|
|
1061
|
+
copy['description'] = override;
|
|
1062
|
+
params[i] = copy;
|
|
896
1063
|
inlined++;
|
|
897
1064
|
}
|
|
898
1065
|
}
|
|
@@ -904,8 +1071,167 @@ export async function bundle(options) {
|
|
|
904
1071
|
break;
|
|
905
1072
|
}
|
|
906
1073
|
}
|
|
1074
|
+
// ── Step 3e: Always inline path-local $refs used as `responses` values ────
|
|
1075
|
+
//
|
|
1076
|
+
// Same mechanism as Step 3d, for `components.responses`: the section does
|
|
1077
|
+
// not survive bundling, so every reuse of a shared response becomes a
|
|
1078
|
+
// path-local $ref to whichever operation SwaggerParser emitted first:
|
|
1079
|
+
//
|
|
1080
|
+
// GET /agent-definitions/{agentDefinitionKey}:
|
|
1081
|
+
// responses:
|
|
1082
|
+
// '401': { $ref: '#/paths/~1clock/get/responses/401' }
|
|
1083
|
+
//
|
|
1084
|
+
// The real Camunda spec carries hundreds of these. Consumers that only
|
|
1085
|
+
// resolve `#/components/...` pointers (e.g. api-test-generator) silently drop
|
|
1086
|
+
// the response.
|
|
1087
|
+
//
|
|
1088
|
+
// Response Objects are never emitted as named types by any generator — the
|
|
1089
|
+
// schemas inside them are, and those keep their `#/components/schemas/*`
|
|
1090
|
+
// refs through the deep copy — so inlining is lossless and done
|
|
1091
|
+
// unconditionally, for the same reason as Step 3d.
|
|
1092
|
+
{
|
|
1093
|
+
const isPathLocalRef = (node) => {
|
|
1094
|
+
if (!node || typeof node !== 'object' || Array.isArray(node))
|
|
1095
|
+
return false;
|
|
1096
|
+
const ref = node['$ref'];
|
|
1097
|
+
return typeof ref === 'string' && ref.startsWith('#/paths/');
|
|
1098
|
+
};
|
|
1099
|
+
// A Response Object requires `description` and allows only these fields
|
|
1100
|
+
// (plus `x-` extensions). Checking the full key set, not just
|
|
1101
|
+
// `description`, is what rejects a Parameter or Schema Object a bad
|
|
1102
|
+
// pointer may land on — both of which may also carry a `description`.
|
|
1103
|
+
const RESPONSE_KEYS = new Set(['description', 'headers', 'content', 'links']);
|
|
1104
|
+
const isResponseObject = (node) => {
|
|
1105
|
+
if (!node || typeof node !== 'object' || Array.isArray(node))
|
|
1106
|
+
return false;
|
|
1107
|
+
const r = node;
|
|
1108
|
+
return (typeof r['description'] === 'string' &&
|
|
1109
|
+
Object.keys(r).every((k) => RESPONSE_KEYS.has(k) || k.startsWith('x-')));
|
|
1110
|
+
};
|
|
1111
|
+
// Shape alone cannot distinguish a Response Object from an
|
|
1112
|
+
// annotation-only Schema Object (`{ description: '…' }` is valid as
|
|
1113
|
+
// both). The target's OpenAPI context can: a response target must live
|
|
1114
|
+
// under a `responses` map (`#/paths/<path>/<method>/responses/<status>`
|
|
1115
|
+
// or `#/components/responses/<name>`). The method segment must be a real
|
|
1116
|
+
// HTTP method and the key a real status code — `x-*` extensions are
|
|
1117
|
+
// arbitrary data — and a pointer that merely ENDS in
|
|
1118
|
+
// `/responses/<status>` (e.g. a nested schema position) is not a
|
|
1119
|
+
// response position.
|
|
1120
|
+
const RESPONSE_TARGET_REF = /^#\/(?:components\/responses\/[^/]+|paths\/~1[^/]*\/(?:get|put|post|delete|options|head|patch|trace)\/responses\/(?!x-)[^/]+)$/;
|
|
1121
|
+
const isResponseTargetRef = (ref) => RESPONSE_TARGET_REF.test(ref);
|
|
1122
|
+
for (let pass = 1; pass <= 20; pass++) {
|
|
1123
|
+
let inlined = 0;
|
|
1124
|
+
forEachResponsesMap(bundled, (responses) => {
|
|
1125
|
+
for (const [status, response] of Object.entries(responses)) {
|
|
1126
|
+
if (status.startsWith('x-'))
|
|
1127
|
+
continue; // extension, not a response
|
|
1128
|
+
if (!isPathLocalRef(response))
|
|
1129
|
+
continue;
|
|
1130
|
+
const ref = response['$ref'];
|
|
1131
|
+
// Follow terminal hops: the snapshots predate inlining, so the
|
|
1132
|
+
// target of an acyclic chain (`/c` → `/b` → `/a`) is still `/b`'s
|
|
1133
|
+
// reference. Cycle-safe: a cycle resolves to undefined and is left
|
|
1134
|
+
// for the survivor guard. The walk only starts from — and only
|
|
1135
|
+
// continues through — pointers that are themselves response
|
|
1136
|
+
// positions: a chain may otherwise lead into an `x-*` extension or
|
|
1137
|
+
// transit a schema position to launder a non-response target.
|
|
1138
|
+
const hopWalk = isResponseTargetRef(ref)
|
|
1139
|
+
? resolveTerminalRef(postNormSnapshot, preNormSnapshot, resolveInternalRef(postNormSnapshot, ref) ??
|
|
1140
|
+
resolveInternalRef(preNormSnapshot, ref), isResponseTargetRef)
|
|
1141
|
+
: { node: undefined };
|
|
1142
|
+
const resolved = hopWalk.node;
|
|
1143
|
+
const intermediateDescription = hopWalk.description;
|
|
1144
|
+
// Anything that is not a Response Object — a primitive, another
|
|
1145
|
+
// object type, a missing target, or a reference cycle — leaves the
|
|
1146
|
+
// $ref in place, uncounted, so the Step 5 guard reports it. The
|
|
1147
|
+
// context check rejects a structurally identical Schema Object.
|
|
1148
|
+
if (isResponseObject(resolved)) {
|
|
1149
|
+
const copy = JSON.parse(JSON.stringify(resolved));
|
|
1150
|
+
// A Reference Object may carry a `description` sibling overriding
|
|
1151
|
+
// the target's (OpenAPI 3.1; 3.0.x processors apply the same
|
|
1152
|
+
// rule). Inlining must not discard that override: the use-site
|
|
1153
|
+
// reference's own sibling wins, then the nearest intermediate
|
|
1154
|
+
// reference's, then the terminal response's. `summary` is NOT
|
|
1155
|
+
// copied — a Response Object has no such field, so emitting it
|
|
1156
|
+
// would turn a valid reference into invalid output.
|
|
1157
|
+
const override = response['description'] ??
|
|
1158
|
+
intermediateDescription;
|
|
1159
|
+
if (typeof override === 'string')
|
|
1160
|
+
copy['description'] = override;
|
|
1161
|
+
responses[status] = copy;
|
|
1162
|
+
inlined++;
|
|
1163
|
+
}
|
|
1164
|
+
}
|
|
1165
|
+
});
|
|
1166
|
+
stats.inlinedPathLocalResponseCount += inlined;
|
|
1167
|
+
if (inlined === 0)
|
|
1168
|
+
break;
|
|
1169
|
+
}
|
|
1170
|
+
}
|
|
1171
|
+
// These guards run BEFORE Step 4: dereferencing would otherwise replace
|
|
1172
|
+
// the rejected refs with their (invalid) targets and hide them.
|
|
1173
|
+
//
|
|
1174
|
+
// Step 3d should have inlined all of these. A survivor means the pointer
|
|
1175
|
+
// could not be resolved, so the bundle is one no generator can consume —
|
|
1176
|
+
// fail loudly rather than emit it.
|
|
1177
|
+
const survivingParameterRefs = findPathLocalParameterRefs(bundled);
|
|
1178
|
+
if (survivingParameterRefs.length > 0 &&
|
|
1179
|
+
!options.allowPathLocalParameterRefs) {
|
|
1180
|
+
throw new Error(`${survivingParameterRefs.length} path-local $ref(s) survived inside parameters arrays:\n` +
|
|
1181
|
+
survivingParameterRefs.map((r) => ` ${r}`).join('\n') +
|
|
1182
|
+
`\n\nThese cannot be resolved by openapi-generator or Microsoft.OpenApi and cause ` +
|
|
1183
|
+
`"duplicate parameter values" failures. Set allowPathLocalParameterRefs ` +
|
|
1184
|
+
`(CLI: --allow-param-refs) to bypass.`);
|
|
1185
|
+
}
|
|
1186
|
+
// Step 3e should have inlined all of these. A survivor points at something
|
|
1187
|
+
// that is not a Response Object, so fail loudly rather than emit it.
|
|
1188
|
+
const survivingResponseRefs = findPathLocalResponseRefs(bundled);
|
|
1189
|
+
if (survivingResponseRefs.length > 0 &&
|
|
1190
|
+
!options.allowPathLocalResponseRefs) {
|
|
1191
|
+
throw new Error(`${survivingResponseRefs.length} path-local $ref(s) survived in responses maps ` +
|
|
1192
|
+
`and could not be inlined (target is missing, cyclic, or not a Response Object):\n` +
|
|
1193
|
+
survivingResponseRefs.map((r) => ` ${r}`).join('\n') +
|
|
1194
|
+
`\n\nConsumers that only resolve #/components/... pointers drop these responses. ` +
|
|
1195
|
+
`Set allowPathLocalResponseRefs (CLI: --allow-response-refs) to bypass.`);
|
|
1196
|
+
}
|
|
907
1197
|
// ── Step 4: Optionally dereference remaining path-local $refs ─────────────
|
|
908
1198
|
if (options.dereferencePathLocalRefs) {
|
|
1199
|
+
// A Reference Object may carry `summary`/`description` siblings
|
|
1200
|
+
// overriding the target's (OpenAPI 3.1; 3.0.x processors apply the same
|
|
1201
|
+
// rule). Expanding the ref must not discard those overrides — the
|
|
1202
|
+
// snapshots predate the inlining passes, so an aliased Path Item still
|
|
1203
|
+
// contains the reference with its siblings, and a naive expansion would
|
|
1204
|
+
// lose them.
|
|
1205
|
+
//
|
|
1206
|
+
// `summary` is only copied when the resolved target supports the field
|
|
1207
|
+
// (a Path Item or Operation Object does; a Response or Parameter Object
|
|
1208
|
+
// does not — copying it there would emit invalid output, the same rule
|
|
1209
|
+
// Steps 3d/3e apply). `description` is supported by every object this
|
|
1210
|
+
// expander can land on.
|
|
1211
|
+
// Path Item (`#/paths/<path>`) or Operation
|
|
1212
|
+
// (`#/paths/<path>/<method>`) positions — the only targets supporting
|
|
1213
|
+
// `summary`.
|
|
1214
|
+
const SUMMARY_TARGET_REF = /^#\/paths\/~1[^/]*(?:\/(?:get|put|post|delete|options|head|patch|trace))?$/;
|
|
1215
|
+
const expand = (refNode) => {
|
|
1216
|
+
const ref = refNode['$ref'];
|
|
1217
|
+
const resolved = resolveInternalRef(postNormSnapshot, ref) ??
|
|
1218
|
+
resolveInternalRef(preNormSnapshot, ref);
|
|
1219
|
+
if (!resolved || typeof resolved !== 'object' || Array.isArray(resolved))
|
|
1220
|
+
return undefined;
|
|
1221
|
+
const copy = JSON.parse(JSON.stringify(resolved));
|
|
1222
|
+
// Decided by the pointer's position, not the target's shape: a Path
|
|
1223
|
+
// Item with only method children carries none of the shape markers.
|
|
1224
|
+
const targetSupportsSummary = SUMMARY_TARGET_REF.test(ref);
|
|
1225
|
+
const siblings = targetSupportsSummary
|
|
1226
|
+
? ['summary', 'description']
|
|
1227
|
+
: ['description'];
|
|
1228
|
+
for (const sibling of siblings) {
|
|
1229
|
+
const override = refNode[sibling];
|
|
1230
|
+
if (typeof override === 'string')
|
|
1231
|
+
copy[sibling] = override;
|
|
1232
|
+
}
|
|
1233
|
+
return copy;
|
|
1234
|
+
};
|
|
909
1235
|
for (let pass = 1; pass <= 20; pass++) {
|
|
910
1236
|
let dereferenced = 0;
|
|
911
1237
|
const seen = new Set();
|
|
@@ -924,10 +1250,9 @@ export async function bundle(options) {
|
|
|
924
1250
|
item['$ref'].startsWith('#/paths/')) {
|
|
925
1251
|
// Prefer post-normalization source (normalized $like, promoted schemas);
|
|
926
1252
|
// fall back to pre-normalization if the path was removed during normalization
|
|
927
|
-
const
|
|
928
|
-
|
|
929
|
-
|
|
930
|
-
node[i] = JSON.parse(JSON.stringify(resolved));
|
|
1253
|
+
const expanded = expand(item);
|
|
1254
|
+
if (expanded) {
|
|
1255
|
+
node[i] = expanded;
|
|
931
1256
|
dereferenced++;
|
|
932
1257
|
}
|
|
933
1258
|
}
|
|
@@ -942,10 +1267,9 @@ export async function bundle(options) {
|
|
|
942
1267
|
const valObj = val;
|
|
943
1268
|
if (typeof valObj['$ref'] === 'string' &&
|
|
944
1269
|
valObj['$ref'].startsWith('#/paths/')) {
|
|
945
|
-
const
|
|
946
|
-
|
|
947
|
-
|
|
948
|
-
obj[key] = JSON.parse(JSON.stringify(resolved));
|
|
1270
|
+
const expanded = expand(valObj);
|
|
1271
|
+
if (expanded) {
|
|
1272
|
+
obj[key] = expanded;
|
|
949
1273
|
dereferenced++;
|
|
950
1274
|
}
|
|
951
1275
|
}
|
|
@@ -991,6 +1315,39 @@ export async function bundle(options) {
|
|
|
991
1315
|
const interior = collapseComponentInteriorRefs(bundled);
|
|
992
1316
|
stats.collapsedComponentInteriorRefCount = interior.collapsed;
|
|
993
1317
|
stats.componentInteriorRefCount = interior.unresolved.length;
|
|
1318
|
+
// ── Step 4d: Collapse $refs that point into a component subtree ──────────
|
|
1319
|
+
//
|
|
1320
|
+
// When a named schema is first reached through another component's
|
|
1321
|
+
// composition, `SwaggerParser.bundle()` emits every other use of it as a
|
|
1322
|
+
// pointer into that component instead of a ref to the schema itself:
|
|
1323
|
+
//
|
|
1324
|
+
// GET /authentication/me -> 200:
|
|
1325
|
+
// $ref: '#/components/schemas/AuthenticatedCamundaUserResult/allOf/0'
|
|
1326
|
+
//
|
|
1327
|
+
// where `allOf/0` is just `{ $ref: '#/components/schemas/CamundaUserResult' }`
|
|
1328
|
+
// (camunda/camunda 1df63b8507). The pointer resolves, but generators name
|
|
1329
|
+
// the target after the pointer: openapi-generator (PHP) emitted a
|
|
1330
|
+
// non-existent `Model0` class. When the pointer lands on a bare `$ref`,
|
|
1331
|
+
// the two are the same schema, so rewrite to the final target. This runs
|
|
1332
|
+
// unconditionally: `--deref-path-local` only handles `#/paths/` refs.
|
|
1333
|
+
// It runs after Step 4/4b because dereferencing copies subtrees from
|
|
1334
|
+
// snapshots taken before this pass, which can reintroduce subtree refs.
|
|
1335
|
+
//
|
|
1336
|
+
// Step 4c already retargets `#/components/schemas/<name>/...` refs and
|
|
1337
|
+
// reports the ones it cannot resolve; a survivor here is one of those
|
|
1338
|
+
// (reported again, with the same wording) or a ref into a non-schema
|
|
1339
|
+
// component subtree, which 4c does not see. Both fail the same way
|
|
1340
|
+
// downstream, so they share the `allowComponentInteriorRefs` bypass.
|
|
1341
|
+
const subtree = collapseComponentSubtreeRefs(bundled);
|
|
1342
|
+
stats.componentSubtreeRefsCollapsed += subtree.collapsed;
|
|
1343
|
+
if (subtree.survivors.length > 0 && !options.allowComponentInteriorRefs) {
|
|
1344
|
+
throw new Error(`${subtree.survivors.length} $ref(s) point inside a component schema and do not resolve ` +
|
|
1345
|
+
`to a named schema:\n` +
|
|
1346
|
+
subtree.survivors.map((r) => ` ${r}`).join('\n') +
|
|
1347
|
+
`\n\nGenerators would name the target after the JSON pointer (e.g. \`Model0\`). ` +
|
|
1348
|
+
`Fix: register the referenced schema as a named component upstream. ` +
|
|
1349
|
+
`Set allowComponentInteriorRefs (CLI: --allow-interior-refs) to bypass.`);
|
|
1350
|
+
}
|
|
994
1351
|
// ── Step 5: Validate ──────────────────────────────────────────────────────
|
|
995
1352
|
// Fail if any inline schemas remain that match multiple component schemas
|
|
996
1353
|
// but could not be disambiguated. These will cause generator failures
|
|
@@ -1011,18 +1368,6 @@ export async function bundle(options) {
|
|
|
1011
1368
|
throw new Error(`${stats.pathLocalLikeRefCount} path-local $like ref(s) survived normalization. ` +
|
|
1012
1369
|
`This will cause generator failures. Set allowPathLocalLikeRefs to bypass.`);
|
|
1013
1370
|
}
|
|
1014
|
-
// Step 3d should have inlined all of these. A survivor means the pointer
|
|
1015
|
-
// could not be resolved, so the bundle is one no generator can consume —
|
|
1016
|
-
// fail loudly rather than emit it.
|
|
1017
|
-
const survivingParameterRefs = findPathLocalParameterRefs(bundled);
|
|
1018
|
-
if (survivingParameterRefs.length > 0 &&
|
|
1019
|
-
!options.allowPathLocalParameterRefs) {
|
|
1020
|
-
throw new Error(`${survivingParameterRefs.length} path-local $ref(s) survived inside parameters arrays:\n` +
|
|
1021
|
-
survivingParameterRefs.map((r) => ` ${r}`).join('\n') +
|
|
1022
|
-
`\n\nThese cannot be resolved by openapi-generator or Microsoft.OpenApi and cause ` +
|
|
1023
|
-
`"duplicate parameter values" failures. Set allowPathLocalParameterRefs ` +
|
|
1024
|
-
`(CLI: --allow-param-refs) to bypass.`);
|
|
1025
|
-
}
|
|
1026
1371
|
// Step 4c could not retarget these: the interior location is not, and does
|
|
1027
1372
|
// not resolve to, a named component, so there is no type to point at.
|
|
1028
1373
|
if (interior.unresolved.length > 0 && !options.allowComponentInteriorRefs) {
|