Skip to content

Commit 02717c9

Browse files
char0nchar0n
committed
feat(reference): add support for OAS 3.1 Path Item dereference
Closes #458
1 parent 1bc0d14 commit 02717c9

File tree

46 files changed

+663
-21
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

46 files changed

+663
-21
lines changed

‎apidom/packages/apidom-ns-openapi-3-1/src/index.ts

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ export {
2828
isOperationElement,
2929
isParameterElement,
3030
isPathItemElement,
31+
isPathItemElementExternal,
3132
isPathsElement,
3233
isReferenceElement,
3334
isReferenceElementExternal,

‎apidom/packages/apidom-ns-openapi-3-1/src/predicates.ts

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -183,6 +183,19 @@ export const isPathItemElement = createPredicate(
183183
},
184184
);
185185

186+
export const isPathItemElementExternal = (element: any): element is PathItemElement => {
187+
if (!isPathItemElement(element)) {
188+
return false;
189+
}
190+
if (!isStringElement(element.$ref)) {
191+
return false;
192+
}
193+
194+
const value = element.$ref.toValue();
195+
196+
return isNonEmptyString(value) && !startsWith('#', value);
197+
};
198+
186199
export const isPathsElement = createPredicate(
187200
({ hasBasicElementProps, isElementType, primitiveEq }) => {
188201
const isElementTypePaths = isElementType('paths');

‎apidom/packages/apidom-ns-openapi-3-1/src/refractor/predicates.ts

Lines changed: 3 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import { MemberElement, isStringElement, isObjectElement, Element } from 'apidom';
2-
import { startsWith, all } from 'ramda';
2+
import { startsWith } from 'ramda';
33

44
export const isOpenApi3_1LikeElement = <T extends Element>(element: T): boolean => {
55
// @ts-ignore
@@ -12,20 +12,8 @@ export const isParameterLikeElement = <T extends Element>(element: T): boolean =
1212
};
1313

1414
export const isReferenceLikeElement = <T extends Element>(element: T): boolean => {
15-
const isAllowedProperty = (property: string): boolean => {
16-
// @ts-ignore
17-
return ['$ref', 'description', 'summary'].includes(property);
18-
};
19-
20-
return (
21-
isObjectElement(element) &&
22-
// @ts-ignore
23-
element.hasKey('$ref') &&
24-
// @ts-ignore
25-
element.keys.length <= 3 &&
26-
// @ts-ignore
27-
all(isAllowedProperty)(element.keys)
28-
);
15+
// @ts-ignore
16+
return isObjectElement(element) && element.hasKey('$ref');
2917
};
3018

3119
export const isRequestBodyLikeElement = <T extends Element>(element: T): boolean => {

‎apidom/packages/apidom-ns-openapi-3-1/test/refractor/elements/Components/__snapshots__/index.ts.snap

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -115,5 +115,14 @@ exports[`refractor elements ComponentsElement should refract to semantic ApiDOM
115115
(ReferenceElement
116116
(MemberElement
117117
(StringElement)
118-
(StringElement)))))))
118+
(StringElement))))
119+
(MemberElement
120+
(StringElement)
121+
(ReferenceElement
122+
(MemberElement
123+
(StringElement)
124+
(StringElement))
125+
(MemberElement
126+
(StringElement)
127+
(ObjectElement)))))))
119128
`;

‎apidom/packages/apidom-ns-openapi-3-1/test/refractor/elements/Components/index.ts

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,10 @@ describe('refractor', function () {
4646
pathItems: {
4747
PathItem1: {},
4848
PathItem2: { $ref: '#/components/pathsItems/PathItem1' },
49+
PathItem3: {
50+
$ref: '#/components/pathsItems/PathItem1',
51+
get: {},
52+
},
4953
},
5054
});
5155

‎apidom/packages/apidom-reference/src/dereference/strategies/openapi-3-1/visitor.ts

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,10 @@ import {
77
isReferenceLikeElement,
88
keyMap,
99
ReferenceElement,
10+
PathItemElement,
1011
SchemaElement,
1112
isReferenceElementExternal,
13+
isPathItemElementExternal,
1214
isSchemaElementExternal,
1315
} from 'apidom-ns-openapi-3-1';
1416

@@ -161,6 +163,81 @@ const OpenApi3_1DereferenceVisitor = stampit({
161163
return fragment;
162164
},
163165

166+
async PathItemElement(pathItemElement: PathItemElement) {
167+
// ignore PathItemElement without $ref field
168+
if (!isStringElement(pathItemElement.$ref)) {
169+
return undefined;
170+
}
171+
172+
// ignore resolving external Reference Objects
173+
if (!this.options.resolve.external && isPathItemElementExternal(pathItemElement)) {
174+
return undefined;
175+
}
176+
177+
// @ts-ignore
178+
const reference = await this.toReference(pathItemElement.$ref.toValue());
179+
180+
this.indirections.push(pathItemElement);
181+
182+
const jsonPointer = uriToPointer(pathItemElement.$ref.toValue());
183+
184+
// possibly non-semantic fragment
185+
let referencedElement = jsonPointerEvaluate(jsonPointer, reference.value.result);
186+
187+
// applying semantics to a fragment
188+
if (isPrimitiveElement(referencedElement)) {
189+
referencedElement = PathItemElement.refract(referencedElement);
190+
}
191+
192+
// detect direct or indirect reference
193+
if (this.indirections.includes(referencedElement)) {
194+
throw new Error('Recursive JSON Pointer detected');
195+
}
196+
197+
// detect maximum depth of dereferencing
198+
if (this.indirections.length > this.options.dereference.maxDepth) {
199+
throw new MaximumDereferenceDepthError(
200+
`Maximum dereference depth of "${this.options.dereference.maxDepth}" has been exceeded in file "${this.reference.uri}"`,
201+
);
202+
}
203+
204+
// dive deep into the fragment
205+
const visitor: any = OpenApi3_1DereferenceVisitor({
206+
reference,
207+
namespace: this.namespace,
208+
indirections: [...this.indirections],
209+
options: this.options,
210+
});
211+
referencedElement = await visitAsync(referencedElement, visitor, {
212+
keyMap,
213+
nodeTypeGetter: getNodeType,
214+
});
215+
216+
this.indirections.pop();
217+
218+
// merge fields from referenced Path Item with referencing one
219+
const mergedResult = new PathItemElement(
220+
// @ts-ignore
221+
[...referencedElement.content],
222+
referencedElement.meta.clone(),
223+
referencedElement.attributes.clone(),
224+
);
225+
// existing keywords from referencing PathItemElement overrides ones from referenced schema
226+
pathItemElement.forEach((value: Element, key: Element, item: Element) => {
227+
mergedResult.remove(key.toValue());
228+
mergedResult.content.push(item);
229+
});
230+
mergedResult.remove('$ref');
231+
232+
// annotate referencing element with info about original referenced element
233+
mergedResult.setMetaProperty('ref-fields', {
234+
$ref: pathItemElement.$ref?.toValue(),
235+
});
236+
237+
// transclude referencing element with merged referenced element
238+
return mergedResult;
239+
},
240+
164241
async SchemaElement(referencingElement: SchemaElement) {
165242
/**
166243
* Skip traversal for already visited schemas and all their child schemas.

‎apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/path-item-object/fixtures/additional-fields/dereferenced.json

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
[
2+
{
3+
"openapi": "3.1.0",
4+
"paths": {
5+
"/path1": {
6+
"summary": "path1 item summary",
7+
"description": "path item description",
8+
"get": {}
9+
},
10+
"/path2": {
11+
"summary": "path2 item summary",
12+
"description": "path item description",
13+
"get": {}
14+
}
15+
}
16+
}
17+
]

‎apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/path-item-object/fixtures/additional-fields/root.json

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{
2+
"openapi": "3.1.0",
3+
"paths": {
4+
"/path1": {
5+
"$ref": "#/paths/~1path2",
6+
"summary": "path1 item summary"
7+
},
8+
"/path2": {
9+
"summary": "path2 item summary",
10+
"description": "path item description",
11+
"get": {}
12+
}
13+
}
14+
}

‎apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/path-item-object/fixtures/direct-external-circular/ex.json

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"$ref": "./root.json#/paths/~1path1"
3+
}

‎apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/path-item-object/fixtures/direct-external-circular/root.json

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"openapi": "3.1.0",
3+
"paths": {
4+
"/path1": {
5+
"$ref": "./ex.json"
6+
}
7+
}
8+
}

‎apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/path-item-object/fixtures/direct-internal-circular/root.json

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"openapi": "3.1.0",
3+
"paths": {
4+
"/path1": {
5+
"$ref": "#/paths/~1path2"
6+
},
7+
"/path2": {
8+
"$ref": "#/paths/~1path1"
9+
}
10+
}
11+
}

‎apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/path-item-object/fixtures/external-indirections/dereferenced.json

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
[
2+
{
3+
"openapi": "3.1.0",
4+
"paths": {
5+
"/path1": {
6+
"summary": "path item summary",
7+
"description": "path item description",
8+
"get": {}
9+
}
10+
}
11+
}
12+
]

‎apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/path-item-object/fixtures/external-indirections/ex1.json

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"$ref": "./ex2.json#/~1path3"
3+
}

‎apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/path-item-object/fixtures/external-indirections/ex2.json

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"/path3": {
3+
"summary": "path item summary",
4+
"description": "path item description",
5+
"get": {}
6+
}
7+
}

‎apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/path-item-object/fixtures/external-indirections/root.json

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"openapi": "3.1.0",
3+
"paths": {
4+
"/path1": {
5+
"$ref": "./ex1.json"
6+
}
7+
}
8+
}

‎apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/path-item-object/fixtures/external-only/dereferenced.json

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
[
2+
{
3+
"openapi": "3.1.0",
4+
"paths": {
5+
"/path1": {
6+
"summary": "path item summary",
7+
"description": "path item description",
8+
"get": {}
9+
}
10+
}
11+
}
12+
]

‎apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/path-item-object/fixtures/external-only/ex.json

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"/path2": {
3+
"summary": "path item summary",
4+
"description": "path item description",
5+
"get": {}
6+
}
7+
}

‎apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/path-item-object/fixtures/external-only/root.json

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"openapi": "3.1.0",
3+
"paths": {
4+
"/path1": {
5+
"$ref": "./ex.json#/~1path2"
6+
}
7+
}
8+
}

‎apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/path-item-object/fixtures/ignore-external/dereferenced.json

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
[
2+
{
3+
"openapi": "3.1.0",
4+
"paths": {
5+
"/path1": {
6+
"$ref": "./ex.json#/~1path2"
7+
}
8+
}
9+
}
10+
]

‎apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/path-item-object/fixtures/ignore-external/ex.json

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"/path2": {
3+
"summary": "path item summary",
4+
"description": "path item description",
5+
"get": {}
6+
}
7+
}

‎apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/path-item-object/fixtures/ignore-external/root.json

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"openapi": "3.1.0",
3+
"paths": {
4+
"/path1": {
5+
"$ref": "./ex.json#/~1path2"
6+
}
7+
}
8+
}

‎apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/path-item-object/fixtures/indirect-external-circular/ex1.json

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"$ref": "./ex2.json"
3+
}

‎apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/path-item-object/fixtures/indirect-external-circular/ex2.json

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"$ref": "./root.json#/paths/~1path1"
3+
}

‎apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/path-item-object/fixtures/indirect-external-circular/root.json

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"openapi": "3.1.0",
3+
"paths": {
4+
"/path1": {
5+
"$ref": "./ex1.json"
6+
}
7+
}
8+
}

‎apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/path-item-object/fixtures/indirect-internal-circular/root.json

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{
2+
"openapi": "3.1.0",
3+
"paths": {
4+
"/path1": {
5+
"$ref": "#/paths/~1path2"
6+
},
7+
"/path2": {
8+
"$ref": "#/paths/~1path3"
9+
},
10+
"/path3": {
11+
"$ref": "#/paths/~1path1"
12+
}
13+
}
14+
}

‎apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/path-item-object/fixtures/internal-external/dereferenced.json

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
[
2+
{
3+
"openapi": "3.1.0",
4+
"paths": {
5+
"/path1": {
6+
"summary": "path item summary",
7+
"description": "path item description",
8+
"get": {}
9+
},
10+
"/path3": {
11+
"summary": "path item summary",
12+
"description": "path item description",
13+
"get": {}
14+
},
15+
"/path4": {
16+
"summary": "path item summary",
17+
"description": "path item description",
18+
"get": {}
19+
}
20+
}
21+
}
22+
]

‎apidom/packages/apidom-reference/test/dereference/strategies/openapi-3-1/path-item-object/fixtures/internal-external/ex.json

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"/path2": {
3+
"summary": "path item summary",
4+
"description": "path item description",
5+
"get": {}
6+
}
7+
}

0 commit comments

Comments
 (0)