@jentic/arazzo-resolver 1.0.0-alpha.10
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/CHANGELOG.md +49 -0
- package/LICENSE +202 -0
- package/NOTICE +4 -0
- package/README.md +490 -0
- package/dist/jentic-arazzo-resolver.browser.js +84468 -0
- package/dist/jentic-arazzo-resolver.browser.min.js +1 -0
- package/package.json +73 -0
- package/src/dereference/arazzo.cjs +272 -0
- package/src/dereference/arazzo.mjs +264 -0
- package/src/dereference/openapi.cjs +259 -0
- package/src/dereference/openapi.mjs +251 -0
- package/src/errors/DereferenceError.cjs +15 -0
- package/src/errors/DereferenceError.mjs +12 -0
- package/src/index.cjs +15 -0
- package/src/index.mjs +3 -0
- package/types/arazzo-resolver.d.ts +217 -0
|
@@ -0,0 +1,259 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
|
|
3
|
+
var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
|
|
4
|
+
exports.__esModule = true;
|
|
5
|
+
exports.defaultOptions = void 0;
|
|
6
|
+
exports.dereference = dereference;
|
|
7
|
+
exports.dereferenceElement = dereferenceElement;
|
|
8
|
+
var _apidomDatamodel = require("@speclynx/apidom-datamodel");
|
|
9
|
+
var _empty = require("@speclynx/apidom-reference/configuration/empty");
|
|
10
|
+
var _openapi = _interopRequireDefault(require("@speclynx/apidom-reference/dereference/strategies/openapi-2"));
|
|
11
|
+
var _openapi2 = _interopRequireDefault(require("@speclynx/apidom-reference/dereference/strategies/openapi-3-0"));
|
|
12
|
+
var _openapi3 = _interopRequireDefault(require("@speclynx/apidom-reference/dereference/strategies/openapi-3-1"));
|
|
13
|
+
var _openapiJson = _interopRequireDefault(require("@speclynx/apidom-reference/parse/parsers/openapi-json-2"));
|
|
14
|
+
var _openapiYaml = _interopRequireDefault(require("@speclynx/apidom-reference/parse/parsers/openapi-yaml-2"));
|
|
15
|
+
var _openapiJson2 = _interopRequireDefault(require("@speclynx/apidom-reference/parse/parsers/openapi-json-3-0"));
|
|
16
|
+
var _openapiYaml2 = _interopRequireDefault(require("@speclynx/apidom-reference/parse/parsers/openapi-yaml-3-0"));
|
|
17
|
+
var _openapiJson3 = _interopRequireDefault(require("@speclynx/apidom-reference/parse/parsers/openapi-json-3-1"));
|
|
18
|
+
var _openapiYaml3 = _interopRequireDefault(require("@speclynx/apidom-reference/parse/parsers/openapi-yaml-3-1"));
|
|
19
|
+
var _json = _interopRequireDefault(require("@speclynx/apidom-reference/parse/parsers/json"));
|
|
20
|
+
var _yaml = _interopRequireDefault(require("@speclynx/apidom-reference/parse/parsers/yaml-1-2"));
|
|
21
|
+
var _binary = _interopRequireDefault(require("@speclynx/apidom-reference/parse/parsers/binary"));
|
|
22
|
+
var _file = _interopRequireDefault(require("@speclynx/apidom-reference/resolve/resolvers/file"));
|
|
23
|
+
var _httpAxios = _interopRequireDefault(require("@speclynx/apidom-reference/resolve/resolvers/http-axios"));
|
|
24
|
+
var _apidomNsOpenapi = require("@speclynx/apidom-ns-openapi-2");
|
|
25
|
+
var _apidomNsOpenapi2 = require("@speclynx/apidom-ns-openapi-3-0");
|
|
26
|
+
var _apidomNsOpenapi3 = require("@speclynx/apidom-ns-openapi-3-1");
|
|
27
|
+
var _apidomCore = require("@speclynx/apidom-core");
|
|
28
|
+
var _DereferenceError = _interopRequireDefault(require("../errors/DereferenceError.cjs"));
|
|
29
|
+
/**
|
|
30
|
+
* Options for dereferencing OpenAPI Documents.
|
|
31
|
+
* @public
|
|
32
|
+
*/
|
|
33
|
+
|
|
34
|
+
/**
|
|
35
|
+
* Default reference options for dereferencing OpenAPI Documents.
|
|
36
|
+
* @public
|
|
37
|
+
*/
|
|
38
|
+
const defaultOptions = exports.defaultOptions = {
|
|
39
|
+
resolve: {
|
|
40
|
+
resolvers: [new _file.default({
|
|
41
|
+
fileAllowList: ['*.json', '*.yaml', '*.yml']
|
|
42
|
+
}), new _httpAxios.default({
|
|
43
|
+
timeout: 5000,
|
|
44
|
+
redirects: 5,
|
|
45
|
+
withCredentials: false
|
|
46
|
+
})]
|
|
47
|
+
},
|
|
48
|
+
parse: {
|
|
49
|
+
parsers: [new _openapiJson.default({
|
|
50
|
+
allowEmpty: false,
|
|
51
|
+
fileExtensions: ['.json']
|
|
52
|
+
}), new _openapiYaml.default({
|
|
53
|
+
allowEmpty: false,
|
|
54
|
+
fileExtensions: ['.yaml', '.yml']
|
|
55
|
+
}), new _openapiJson2.default({
|
|
56
|
+
allowEmpty: false,
|
|
57
|
+
fileExtensions: ['.json']
|
|
58
|
+
}), new _openapiYaml2.default({
|
|
59
|
+
allowEmpty: false,
|
|
60
|
+
fileExtensions: ['.yaml', '.yml']
|
|
61
|
+
}), new _openapiJson3.default({
|
|
62
|
+
allowEmpty: false,
|
|
63
|
+
fileExtensions: ['.json']
|
|
64
|
+
}), new _openapiYaml3.default({
|
|
65
|
+
allowEmpty: false,
|
|
66
|
+
fileExtensions: ['.yaml', '.yml']
|
|
67
|
+
}), new _json.default({
|
|
68
|
+
allowEmpty: false,
|
|
69
|
+
fileExtensions: ['.json']
|
|
70
|
+
}), new _yaml.default({
|
|
71
|
+
allowEmpty: false,
|
|
72
|
+
fileExtensions: ['.yaml', '.yml']
|
|
73
|
+
}), new _binary.default({
|
|
74
|
+
allowEmpty: false
|
|
75
|
+
})],
|
|
76
|
+
parserOpts: {
|
|
77
|
+
sourceMap: false,
|
|
78
|
+
strict: true
|
|
79
|
+
}
|
|
80
|
+
},
|
|
81
|
+
dereference: {
|
|
82
|
+
strategies: [new _openapi.default(), new _openapi2.default(), new _openapi3.default()],
|
|
83
|
+
strategyOpts: {}
|
|
84
|
+
}
|
|
85
|
+
};
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* Dereferences an OpenAPI Document from a file system path or HTTP(S) URL.
|
|
89
|
+
*
|
|
90
|
+
* This function resolves all JSON References ($ref) in the OpenAPI Document.
|
|
91
|
+
*
|
|
92
|
+
* Supports OpenAPI 2.0 (Swagger), OpenAPI 3.0.x, and OpenAPI 3.1.x.
|
|
93
|
+
*
|
|
94
|
+
* @param uri - A file system path or HTTP(S) URL to the OpenAPI Document
|
|
95
|
+
* @param options - Reference options (uses defaultOptions when not provided)
|
|
96
|
+
* @returns A promise that resolves to the dereferenced OpenAPI Document as ApiDOM element
|
|
97
|
+
* @throws DereferenceError - When dereferencing fails or document is not an OpenAPI specification. The original error is available via the `cause` property.
|
|
98
|
+
*
|
|
99
|
+
* @example
|
|
100
|
+
* // Dereference from file
|
|
101
|
+
* const result = await dereferenceOpenAPI('/path/to/openapi.json');
|
|
102
|
+
*
|
|
103
|
+
* @example
|
|
104
|
+
* // Dereference from URL
|
|
105
|
+
* const result = await dereferenceOpenAPI('https://example.com/openapi.yaml');
|
|
106
|
+
*
|
|
107
|
+
* @example
|
|
108
|
+
* // Dereference with custom options
|
|
109
|
+
* const result = await dereferenceOpenAPI('/path/to/openapi.json', customReferenceOptions);
|
|
110
|
+
* @public
|
|
111
|
+
*/
|
|
112
|
+
async function dereference(uri, options = {}) {
|
|
113
|
+
const mergedOptions = (0, _empty.mergeOptions)(defaultOptions, options);
|
|
114
|
+
try {
|
|
115
|
+
const parseResult = await (0, _empty.dereference)(uri, mergedOptions);
|
|
116
|
+
|
|
117
|
+
// validate that the dereferenced document is an OpenAPI specification
|
|
118
|
+
if (!isOpenApiElement(parseResult.api)) {
|
|
119
|
+
throw new _empty.UnmatchedDereferenceStrategyError(`Could not find a dereference strategy that can dereference "${uri}" as an OpenAPI specification`);
|
|
120
|
+
}
|
|
121
|
+
parseResult.meta.set('retrievalURI', uri);
|
|
122
|
+
return parseResult;
|
|
123
|
+
} catch (error) {
|
|
124
|
+
throw new _DereferenceError.default(`Failed to dereference OpenAPI Document at "${uri}"`, {
|
|
125
|
+
cause: error
|
|
126
|
+
});
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
/**
|
|
131
|
+
* Dereferences an ApiDOM element representing an OpenAPI Document.
|
|
132
|
+
*
|
|
133
|
+
* This function resolves all JSON References ($ref) in the OpenAPI Document element.
|
|
134
|
+
*
|
|
135
|
+
* Supported scenarios:
|
|
136
|
+
* - ParseResultElement with retrievalURI metadata: baseURI derived automatically
|
|
137
|
+
* - ParseResultElement without retrievalURI: requires `options.resolve.baseURI`
|
|
138
|
+
* - Child element (e.g., PathItemElement) with parseResult in strategyOpts:
|
|
139
|
+
* requires `options.dereference.strategyOpts.parseResult` for component resolution,
|
|
140
|
+
* and `options.resolve.baseURI` if parseResult lacks retrievalURI metadata
|
|
141
|
+
*
|
|
142
|
+
* @param element - An ApiDOM element (ParseResultElement or child element like PathItemElement)
|
|
143
|
+
* @param options - Reference options (uses defaultOptions when not provided)
|
|
144
|
+
* @returns A promise that resolves to the dereferenced element
|
|
145
|
+
* @throws DereferenceError - When baseURI is required but not provided, or when dereferencing fails
|
|
146
|
+
*
|
|
147
|
+
* @example
|
|
148
|
+
* Dereference ParseResultElement with retrievalURI (from file parsing)
|
|
149
|
+
* ```typescript
|
|
150
|
+
* import { parseOpenAPI } from '@jentic/arazzo-parser';
|
|
151
|
+
*
|
|
152
|
+
* const parseResult = await parseOpenAPI('/path/to/openapi.json');
|
|
153
|
+
* const dereferenced = await dereferenceOpenAPIElement(parseResult);
|
|
154
|
+
* ```
|
|
155
|
+
*
|
|
156
|
+
* @example
|
|
157
|
+
* Dereference ParseResultElement without retrievalURI (from inline parsing)
|
|
158
|
+
* ```typescript
|
|
159
|
+
* const parseResult = await parseOpenAPI({ openapi: '3.1.0', ... });
|
|
160
|
+
* const dereferenced = await dereferenceOpenAPIElement(parseResult, {
|
|
161
|
+
* resolve: { baseURI: 'https://example.com/openapi.json' },
|
|
162
|
+
* });
|
|
163
|
+
* ```
|
|
164
|
+
*
|
|
165
|
+
* @example
|
|
166
|
+
* Dereference child element (e.g., PathItemElement)
|
|
167
|
+
* ```typescript
|
|
168
|
+
* const parseResult = await parseOpenAPI('/path/to/openapi.json');
|
|
169
|
+
* const pathItem = parseResult.api.paths.get('/users');
|
|
170
|
+
* const dereferenced = await dereferenceOpenAPIElement(pathItem, {
|
|
171
|
+
* dereference: { strategyOpts: { parseResult } },
|
|
172
|
+
* });
|
|
173
|
+
* ```
|
|
174
|
+
* @public
|
|
175
|
+
*/
|
|
176
|
+
async function dereferenceElement(element, options = {}) {
|
|
177
|
+
const mergedOptions = (0, _empty.mergeOptions)(defaultOptions, options);
|
|
178
|
+
const refSet = mergedOptions.dereference?.refSet ?? new _empty.ReferenceSet();
|
|
179
|
+
let baseURI = mergedOptions.resolve?.baseURI;
|
|
180
|
+
let mediaType = 'text/plain';
|
|
181
|
+
if (refSet.size === 0) {
|
|
182
|
+
if ((0, _apidomDatamodel.isParseResultElement)(element)) {
|
|
183
|
+
if (isOpenApiElement(element.api)) {
|
|
184
|
+
mediaType = inferOpenApiMediaType(element.api);
|
|
185
|
+
}
|
|
186
|
+
if (element.hasMetaProperty('retrievalURI')) {
|
|
187
|
+
baseURI = (0, _apidomCore.toValue)(element.meta.get('retrievalURI'));
|
|
188
|
+
} else if (!baseURI) {
|
|
189
|
+
throw new _DereferenceError.default('baseURI option is required when dereferencing a ParseResultElement without retrievalURI metadata');
|
|
190
|
+
}
|
|
191
|
+
} else if ((0, _apidomDatamodel.isParseResultElement)(mergedOptions.dereference?.strategyOpts?.parseResult)) {
|
|
192
|
+
// dereferencing child element requires refSet for component resolution
|
|
193
|
+
const {
|
|
194
|
+
parseResult
|
|
195
|
+
} = mergedOptions.dereference.strategyOpts;
|
|
196
|
+
let rootURI;
|
|
197
|
+
if (isOpenApiElement(parseResult.api)) {
|
|
198
|
+
mediaType = inferOpenApiMediaType(parseResult.api);
|
|
199
|
+
}
|
|
200
|
+
if (parseResult.hasMetaProperty('retrievalURI')) {
|
|
201
|
+
rootURI = (0, _apidomCore.toValue)(parseResult.meta.get('retrievalURI'));
|
|
202
|
+
} else if (baseURI) {
|
|
203
|
+
rootURI = baseURI;
|
|
204
|
+
} else {
|
|
205
|
+
throw new _DereferenceError.default('baseURI option is required when dereferencing a child element without retrievalURI metadata');
|
|
206
|
+
}
|
|
207
|
+
const elementReference = new _empty.Reference({
|
|
208
|
+
uri: `${rootURI}#fragment`,
|
|
209
|
+
value: new _apidomDatamodel.ParseResultElement([element])
|
|
210
|
+
});
|
|
211
|
+
const rootReference = new _empty.Reference({
|
|
212
|
+
uri: rootURI,
|
|
213
|
+
value: parseResult
|
|
214
|
+
});
|
|
215
|
+
refSet.add(elementReference).add(rootReference);
|
|
216
|
+
baseURI = rootURI;
|
|
217
|
+
}
|
|
218
|
+
}
|
|
219
|
+
try {
|
|
220
|
+
return await (0, _empty.dereferenceApiDOM)(element, (0, _empty.mergeOptions)(mergedOptions, {
|
|
221
|
+
resolve: {
|
|
222
|
+
baseURI
|
|
223
|
+
},
|
|
224
|
+
parse: {
|
|
225
|
+
mediaType
|
|
226
|
+
},
|
|
227
|
+
dereference: {
|
|
228
|
+
refSet
|
|
229
|
+
}
|
|
230
|
+
}));
|
|
231
|
+
} catch (error) {
|
|
232
|
+
throw new _DereferenceError.default('Failed to dereference OpenAPI Document', {
|
|
233
|
+
cause: error
|
|
234
|
+
});
|
|
235
|
+
}
|
|
236
|
+
}
|
|
237
|
+
|
|
238
|
+
/**
|
|
239
|
+
* Checks if the element is a valid OpenAPI specification element.
|
|
240
|
+
*/
|
|
241
|
+
function isOpenApiElement(element) {
|
|
242
|
+
return (0, _apidomNsOpenapi.isSwaggerElement)(element) || (0, _apidomNsOpenapi2.isOpenApi3_0Element)(element) || (0, _apidomNsOpenapi3.isOpenApi3_1Element)(element);
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
/**
|
|
246
|
+
* Gets the appropriate mediaType for an OpenAPI element.
|
|
247
|
+
*/
|
|
248
|
+
function inferOpenApiMediaType(element) {
|
|
249
|
+
if ((0, _apidomNsOpenapi.isSwaggerElement)(element)) {
|
|
250
|
+
return _apidomNsOpenapi.mediaTypes.latest();
|
|
251
|
+
}
|
|
252
|
+
if ((0, _apidomNsOpenapi2.isOpenApi3_0Element)(element)) {
|
|
253
|
+
return _apidomNsOpenapi2.mediaTypes.latest();
|
|
254
|
+
}
|
|
255
|
+
if ((0, _apidomNsOpenapi3.isOpenApi3_1Element)(element)) {
|
|
256
|
+
return _apidomNsOpenapi3.mediaTypes.latest();
|
|
257
|
+
}
|
|
258
|
+
return 'text/plain';
|
|
259
|
+
}
|
|
@@ -0,0 +1,251 @@
|
|
|
1
|
+
import { isParseResultElement, ParseResultElement } from '@speclynx/apidom-datamodel';
|
|
2
|
+
import { dereference as dereferenceURI, dereferenceApiDOM as dereferenceApiDOMElement, mergeOptions, ReferenceSet, Reference, UnmatchedDereferenceStrategyError } from '@speclynx/apidom-reference/configuration/empty';
|
|
3
|
+
import OpenAPI2DereferenceStrategy from '@speclynx/apidom-reference/dereference/strategies/openapi-2';
|
|
4
|
+
import OpenAPI3_0DereferenceStrategy from '@speclynx/apidom-reference/dereference/strategies/openapi-3-0';
|
|
5
|
+
import OpenAPI3_1DereferenceStrategy from '@speclynx/apidom-reference/dereference/strategies/openapi-3-1';
|
|
6
|
+
import OpenApiJSON2Parser from '@speclynx/apidom-reference/parse/parsers/openapi-json-2';
|
|
7
|
+
import OpenApiYAML2Parser from '@speclynx/apidom-reference/parse/parsers/openapi-yaml-2';
|
|
8
|
+
import OpenApiJSON3_0Parser from '@speclynx/apidom-reference/parse/parsers/openapi-json-3-0';
|
|
9
|
+
import OpenApiYAML3_0Parser from '@speclynx/apidom-reference/parse/parsers/openapi-yaml-3-0';
|
|
10
|
+
import OpenApiJSON3_1Parser from '@speclynx/apidom-reference/parse/parsers/openapi-json-3-1';
|
|
11
|
+
import OpenApiYAML3_1Parser from '@speclynx/apidom-reference/parse/parsers/openapi-yaml-3-1';
|
|
12
|
+
import JSONParser from '@speclynx/apidom-reference/parse/parsers/json';
|
|
13
|
+
import YAMLParser from '@speclynx/apidom-reference/parse/parsers/yaml-1-2';
|
|
14
|
+
import BinaryParser from '@speclynx/apidom-reference/parse/parsers/binary';
|
|
15
|
+
import FileResolver from '@speclynx/apidom-reference/resolve/resolvers/file';
|
|
16
|
+
import HTTPResolverAxios from '@speclynx/apidom-reference/resolve/resolvers/http-axios';
|
|
17
|
+
import { isSwaggerElement, mediaTypes as openApi2MediaTypes } from '@speclynx/apidom-ns-openapi-2';
|
|
18
|
+
import { isOpenApi3_0Element, mediaTypes as openApi3_0MediaTypes } from '@speclynx/apidom-ns-openapi-3-0';
|
|
19
|
+
import { isOpenApi3_1Element, mediaTypes as openApi3_1MediaTypes } from '@speclynx/apidom-ns-openapi-3-1';
|
|
20
|
+
import { toValue } from '@speclynx/apidom-core';
|
|
21
|
+
import DereferenceError from "../errors/DereferenceError.mjs";
|
|
22
|
+
/**
|
|
23
|
+
* Options for dereferencing OpenAPI Documents.
|
|
24
|
+
* @public
|
|
25
|
+
*/
|
|
26
|
+
/**
|
|
27
|
+
* Default reference options for dereferencing OpenAPI Documents.
|
|
28
|
+
* @public
|
|
29
|
+
*/
|
|
30
|
+
export const defaultOptions = {
|
|
31
|
+
resolve: {
|
|
32
|
+
resolvers: [new FileResolver({
|
|
33
|
+
fileAllowList: ['*.json', '*.yaml', '*.yml']
|
|
34
|
+
}), new HTTPResolverAxios({
|
|
35
|
+
timeout: 5000,
|
|
36
|
+
redirects: 5,
|
|
37
|
+
withCredentials: false
|
|
38
|
+
})]
|
|
39
|
+
},
|
|
40
|
+
parse: {
|
|
41
|
+
parsers: [new OpenApiJSON2Parser({
|
|
42
|
+
allowEmpty: false,
|
|
43
|
+
fileExtensions: ['.json']
|
|
44
|
+
}), new OpenApiYAML2Parser({
|
|
45
|
+
allowEmpty: false,
|
|
46
|
+
fileExtensions: ['.yaml', '.yml']
|
|
47
|
+
}), new OpenApiJSON3_0Parser({
|
|
48
|
+
allowEmpty: false,
|
|
49
|
+
fileExtensions: ['.json']
|
|
50
|
+
}), new OpenApiYAML3_0Parser({
|
|
51
|
+
allowEmpty: false,
|
|
52
|
+
fileExtensions: ['.yaml', '.yml']
|
|
53
|
+
}), new OpenApiJSON3_1Parser({
|
|
54
|
+
allowEmpty: false,
|
|
55
|
+
fileExtensions: ['.json']
|
|
56
|
+
}), new OpenApiYAML3_1Parser({
|
|
57
|
+
allowEmpty: false,
|
|
58
|
+
fileExtensions: ['.yaml', '.yml']
|
|
59
|
+
}), new JSONParser({
|
|
60
|
+
allowEmpty: false,
|
|
61
|
+
fileExtensions: ['.json']
|
|
62
|
+
}), new YAMLParser({
|
|
63
|
+
allowEmpty: false,
|
|
64
|
+
fileExtensions: ['.yaml', '.yml']
|
|
65
|
+
}), new BinaryParser({
|
|
66
|
+
allowEmpty: false
|
|
67
|
+
})],
|
|
68
|
+
parserOpts: {
|
|
69
|
+
sourceMap: false,
|
|
70
|
+
strict: true
|
|
71
|
+
}
|
|
72
|
+
},
|
|
73
|
+
dereference: {
|
|
74
|
+
strategies: [new OpenAPI2DereferenceStrategy(), new OpenAPI3_0DereferenceStrategy(), new OpenAPI3_1DereferenceStrategy()],
|
|
75
|
+
strategyOpts: {}
|
|
76
|
+
}
|
|
77
|
+
};
|
|
78
|
+
|
|
79
|
+
/**
|
|
80
|
+
* Dereferences an OpenAPI Document from a file system path or HTTP(S) URL.
|
|
81
|
+
*
|
|
82
|
+
* This function resolves all JSON References ($ref) in the OpenAPI Document.
|
|
83
|
+
*
|
|
84
|
+
* Supports OpenAPI 2.0 (Swagger), OpenAPI 3.0.x, and OpenAPI 3.1.x.
|
|
85
|
+
*
|
|
86
|
+
* @param uri - A file system path or HTTP(S) URL to the OpenAPI Document
|
|
87
|
+
* @param options - Reference options (uses defaultOptions when not provided)
|
|
88
|
+
* @returns A promise that resolves to the dereferenced OpenAPI Document as ApiDOM element
|
|
89
|
+
* @throws DereferenceError - When dereferencing fails or document is not an OpenAPI specification. The original error is available via the `cause` property.
|
|
90
|
+
*
|
|
91
|
+
* @example
|
|
92
|
+
* // Dereference from file
|
|
93
|
+
* const result = await dereferenceOpenAPI('/path/to/openapi.json');
|
|
94
|
+
*
|
|
95
|
+
* @example
|
|
96
|
+
* // Dereference from URL
|
|
97
|
+
* const result = await dereferenceOpenAPI('https://example.com/openapi.yaml');
|
|
98
|
+
*
|
|
99
|
+
* @example
|
|
100
|
+
* // Dereference with custom options
|
|
101
|
+
* const result = await dereferenceOpenAPI('/path/to/openapi.json', customReferenceOptions);
|
|
102
|
+
* @public
|
|
103
|
+
*/
|
|
104
|
+
export async function dereference(uri, options = {}) {
|
|
105
|
+
const mergedOptions = mergeOptions(defaultOptions, options);
|
|
106
|
+
try {
|
|
107
|
+
const parseResult = await dereferenceURI(uri, mergedOptions);
|
|
108
|
+
|
|
109
|
+
// validate that the dereferenced document is an OpenAPI specification
|
|
110
|
+
if (!isOpenApiElement(parseResult.api)) {
|
|
111
|
+
throw new UnmatchedDereferenceStrategyError(`Could not find a dereference strategy that can dereference "${uri}" as an OpenAPI specification`);
|
|
112
|
+
}
|
|
113
|
+
parseResult.meta.set('retrievalURI', uri);
|
|
114
|
+
return parseResult;
|
|
115
|
+
} catch (error) {
|
|
116
|
+
throw new DereferenceError(`Failed to dereference OpenAPI Document at "${uri}"`, {
|
|
117
|
+
cause: error
|
|
118
|
+
});
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
/**
|
|
123
|
+
* Dereferences an ApiDOM element representing an OpenAPI Document.
|
|
124
|
+
*
|
|
125
|
+
* This function resolves all JSON References ($ref) in the OpenAPI Document element.
|
|
126
|
+
*
|
|
127
|
+
* Supported scenarios:
|
|
128
|
+
* - ParseResultElement with retrievalURI metadata: baseURI derived automatically
|
|
129
|
+
* - ParseResultElement without retrievalURI: requires `options.resolve.baseURI`
|
|
130
|
+
* - Child element (e.g., PathItemElement) with parseResult in strategyOpts:
|
|
131
|
+
* requires `options.dereference.strategyOpts.parseResult` for component resolution,
|
|
132
|
+
* and `options.resolve.baseURI` if parseResult lacks retrievalURI metadata
|
|
133
|
+
*
|
|
134
|
+
* @param element - An ApiDOM element (ParseResultElement or child element like PathItemElement)
|
|
135
|
+
* @param options - Reference options (uses defaultOptions when not provided)
|
|
136
|
+
* @returns A promise that resolves to the dereferenced element
|
|
137
|
+
* @throws DereferenceError - When baseURI is required but not provided, or when dereferencing fails
|
|
138
|
+
*
|
|
139
|
+
* @example
|
|
140
|
+
* Dereference ParseResultElement with retrievalURI (from file parsing)
|
|
141
|
+
* ```typescript
|
|
142
|
+
* import { parseOpenAPI } from '@jentic/arazzo-parser';
|
|
143
|
+
*
|
|
144
|
+
* const parseResult = await parseOpenAPI('/path/to/openapi.json');
|
|
145
|
+
* const dereferenced = await dereferenceOpenAPIElement(parseResult);
|
|
146
|
+
* ```
|
|
147
|
+
*
|
|
148
|
+
* @example
|
|
149
|
+
* Dereference ParseResultElement without retrievalURI (from inline parsing)
|
|
150
|
+
* ```typescript
|
|
151
|
+
* const parseResult = await parseOpenAPI({ openapi: '3.1.0', ... });
|
|
152
|
+
* const dereferenced = await dereferenceOpenAPIElement(parseResult, {
|
|
153
|
+
* resolve: { baseURI: 'https://example.com/openapi.json' },
|
|
154
|
+
* });
|
|
155
|
+
* ```
|
|
156
|
+
*
|
|
157
|
+
* @example
|
|
158
|
+
* Dereference child element (e.g., PathItemElement)
|
|
159
|
+
* ```typescript
|
|
160
|
+
* const parseResult = await parseOpenAPI('/path/to/openapi.json');
|
|
161
|
+
* const pathItem = parseResult.api.paths.get('/users');
|
|
162
|
+
* const dereferenced = await dereferenceOpenAPIElement(pathItem, {
|
|
163
|
+
* dereference: { strategyOpts: { parseResult } },
|
|
164
|
+
* });
|
|
165
|
+
* ```
|
|
166
|
+
* @public
|
|
167
|
+
*/
|
|
168
|
+
export async function dereferenceElement(element, options = {}) {
|
|
169
|
+
const mergedOptions = mergeOptions(defaultOptions, options);
|
|
170
|
+
const refSet = mergedOptions.dereference?.refSet ?? new ReferenceSet();
|
|
171
|
+
let baseURI = mergedOptions.resolve?.baseURI;
|
|
172
|
+
let mediaType = 'text/plain';
|
|
173
|
+
if (refSet.size === 0) {
|
|
174
|
+
if (isParseResultElement(element)) {
|
|
175
|
+
if (isOpenApiElement(element.api)) {
|
|
176
|
+
mediaType = inferOpenApiMediaType(element.api);
|
|
177
|
+
}
|
|
178
|
+
if (element.hasMetaProperty('retrievalURI')) {
|
|
179
|
+
baseURI = toValue(element.meta.get('retrievalURI'));
|
|
180
|
+
} else if (!baseURI) {
|
|
181
|
+
throw new DereferenceError('baseURI option is required when dereferencing a ParseResultElement without retrievalURI metadata');
|
|
182
|
+
}
|
|
183
|
+
} else if (isParseResultElement(mergedOptions.dereference?.strategyOpts?.parseResult)) {
|
|
184
|
+
// dereferencing child element requires refSet for component resolution
|
|
185
|
+
const {
|
|
186
|
+
parseResult
|
|
187
|
+
} = mergedOptions.dereference.strategyOpts;
|
|
188
|
+
let rootURI;
|
|
189
|
+
if (isOpenApiElement(parseResult.api)) {
|
|
190
|
+
mediaType = inferOpenApiMediaType(parseResult.api);
|
|
191
|
+
}
|
|
192
|
+
if (parseResult.hasMetaProperty('retrievalURI')) {
|
|
193
|
+
rootURI = toValue(parseResult.meta.get('retrievalURI'));
|
|
194
|
+
} else if (baseURI) {
|
|
195
|
+
rootURI = baseURI;
|
|
196
|
+
} else {
|
|
197
|
+
throw new DereferenceError('baseURI option is required when dereferencing a child element without retrievalURI metadata');
|
|
198
|
+
}
|
|
199
|
+
const elementReference = new Reference({
|
|
200
|
+
uri: `${rootURI}#fragment`,
|
|
201
|
+
value: new ParseResultElement([element])
|
|
202
|
+
});
|
|
203
|
+
const rootReference = new Reference({
|
|
204
|
+
uri: rootURI,
|
|
205
|
+
value: parseResult
|
|
206
|
+
});
|
|
207
|
+
refSet.add(elementReference).add(rootReference);
|
|
208
|
+
baseURI = rootURI;
|
|
209
|
+
}
|
|
210
|
+
}
|
|
211
|
+
try {
|
|
212
|
+
return await dereferenceApiDOMElement(element, mergeOptions(mergedOptions, {
|
|
213
|
+
resolve: {
|
|
214
|
+
baseURI
|
|
215
|
+
},
|
|
216
|
+
parse: {
|
|
217
|
+
mediaType
|
|
218
|
+
},
|
|
219
|
+
dereference: {
|
|
220
|
+
refSet
|
|
221
|
+
}
|
|
222
|
+
}));
|
|
223
|
+
} catch (error) {
|
|
224
|
+
throw new DereferenceError('Failed to dereference OpenAPI Document', {
|
|
225
|
+
cause: error
|
|
226
|
+
});
|
|
227
|
+
}
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
/**
|
|
231
|
+
* Checks if the element is a valid OpenAPI specification element.
|
|
232
|
+
*/
|
|
233
|
+
function isOpenApiElement(element) {
|
|
234
|
+
return isSwaggerElement(element) || isOpenApi3_0Element(element) || isOpenApi3_1Element(element);
|
|
235
|
+
}
|
|
236
|
+
|
|
237
|
+
/**
|
|
238
|
+
* Gets the appropriate mediaType for an OpenAPI element.
|
|
239
|
+
*/
|
|
240
|
+
function inferOpenApiMediaType(element) {
|
|
241
|
+
if (isSwaggerElement(element)) {
|
|
242
|
+
return openApi2MediaTypes.latest();
|
|
243
|
+
}
|
|
244
|
+
if (isOpenApi3_0Element(element)) {
|
|
245
|
+
return openApi3_0MediaTypes.latest();
|
|
246
|
+
}
|
|
247
|
+
if (isOpenApi3_1Element(element)) {
|
|
248
|
+
return openApi3_1MediaTypes.latest();
|
|
249
|
+
}
|
|
250
|
+
return 'text/plain';
|
|
251
|
+
}
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
|
|
3
|
+
exports.__esModule = true;
|
|
4
|
+
exports.default = void 0;
|
|
5
|
+
var _apidomError = require("@speclynx/apidom-error");
|
|
6
|
+
/**
|
|
7
|
+
* Error thrown when dereferencing an Arazzo document or element fails.
|
|
8
|
+
* @public
|
|
9
|
+
*/
|
|
10
|
+
class DereferenceError extends _apidomError.ApiDOMError {
|
|
11
|
+
constructor(message, options) {
|
|
12
|
+
super(message, options);
|
|
13
|
+
}
|
|
14
|
+
}
|
|
15
|
+
var _default = exports.default = DereferenceError;
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import { ApiDOMError } from '@speclynx/apidom-error';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Error thrown when dereferencing an Arazzo document or element fails.
|
|
5
|
+
* @public
|
|
6
|
+
*/
|
|
7
|
+
class DereferenceError extends ApiDOMError {
|
|
8
|
+
constructor(message, options) {
|
|
9
|
+
super(message, options);
|
|
10
|
+
}
|
|
11
|
+
}
|
|
12
|
+
export default DereferenceError;
|
package/src/index.cjs
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
|
|
3
|
+
var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
|
|
4
|
+
exports.__esModule = true;
|
|
5
|
+
exports.dereferenceOpenAPIElement = exports.dereferenceOpenAPI = exports.dereferenceArazzoElement = exports.dereferenceArazzo = exports.defaultDereferenceOpenAPIOptions = exports.defaultDereferenceArazzoOptions = exports.DereferenceError = void 0;
|
|
6
|
+
var _arazzo = require("./dereference/arazzo.cjs");
|
|
7
|
+
exports.defaultDereferenceArazzoOptions = _arazzo.defaultOptions;
|
|
8
|
+
exports.dereferenceArazzo = _arazzo.dereference;
|
|
9
|
+
exports.dereferenceArazzoElement = _arazzo.dereferenceElement;
|
|
10
|
+
var _openapi = require("./dereference/openapi.cjs");
|
|
11
|
+
exports.defaultDereferenceOpenAPIOptions = _openapi.defaultOptions;
|
|
12
|
+
exports.dereferenceOpenAPI = _openapi.dereference;
|
|
13
|
+
exports.dereferenceOpenAPIElement = _openapi.dereferenceElement;
|
|
14
|
+
var _DereferenceError = _interopRequireDefault(require("./errors/DereferenceError.cjs"));
|
|
15
|
+
exports.DereferenceError = _DereferenceError.default;
|
package/src/index.mjs
ADDED
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
export { defaultOptions as defaultDereferenceArazzoOptions, dereference as dereferenceArazzo, dereferenceElement as dereferenceArazzoElement } from "./dereference/arazzo.mjs";
|
|
2
|
+
export { defaultOptions as defaultDereferenceOpenAPIOptions, dereference as dereferenceOpenAPI, dereferenceElement as dereferenceOpenAPIElement } from "./dereference/openapi.mjs";
|
|
3
|
+
export { default as DereferenceError } from "./errors/DereferenceError.mjs";
|