@scalar/openapi-parser - npm Package Compare versions

Comparing version 0.13.0 to 0.14.0

CHANGELOG.md

 # @scalar/openapi-parser
 
+## 0.14.0
+
+### Minor Changes
+
+- ee3eb77: feat(openapi-parser): bundle openapi documents
+
 ## 0.13.0
@@ -4,0 +10,0 @@

dist/index.d.ts

@@ -17,3 +17,4 @@ export { dereference } from './utils/dereference.js';
 export { validate } from './utils/validate.js';
+export { bundle, fetchUrls, readFiles } from './utils/bundle/index.js';
 export type { LoadResult, Filesystem, AnyObject, ErrorObject } from './types/index.js';
 //# sourceMappingURL=index.d.ts.map

dist/index.js

@@ -17,5 +17,8 @@ import { dereference } from "./utils/dereference.js";
 import { validate } from "./utils/validate.js";
+import { bundle, fetchUrls, readFiles } from "./utils/bundle/index.js";
 export {
+  bundle,
   dereference,
   escapeJsonPointer,
+  fetchUrls,
   filter,
@@ -26,2 +29,3 @@ isJson,
   normalize,
+  readFiles,
   sanitize,
@@ -28,0 +32,0 @@ toJson,

dist/types/index.d.ts

@@ -8,2 +8,3 @@ import type { OpenAPI } from '@scalar/openapi-types';
 export type AnyObject = Record<string, any>;
+export type UnknownObject = Record<string, unknown>;
 /**
@@ -10,0 +11,0 @@ * JSON, YAML or object representation of an OpenAPI API definition

dist/utils/normalize.js

@@ -15,4 +15,4 @@ import { parse } from "yaml";
       const hasColon = /^[^:]+:/.test(content);
-      const isMultiLine = content.includes("\n");
-      if (!hasColon || !isMultiLine) {
+      const isJson = content.slice(0, 50).trimStart().startsWith("{");
+      if (!hasColon || isJson) {
         return void 0;
@@ -19,0 +19,0 @@ }

package.json

@@ -20,3 +20,3 @@ {
   ],
-  "version": "0.13.0",
+  "version": "0.14.0",
   "engines": {
@@ -62,3 +62,3 @@ "node": ">=20"
     "@types/node": "^20.17.10",
-    "glob": "^10.3.10",
+    "fastify": "^4.26.2",
     "json-to-ast": "^2.1.0",
@@ -69,4 +69,4 @@ "just-diff": "^6.0.2",
     "@scalar/openapi-types": "0.3.1",
-    "@scalar/build-tooling": "0.2.1",
-    "@scalar/types": "0.2.1"
+    "@scalar/types": "0.2.1",
+    "@scalar/build-tooling": "0.2.1"
   },
@@ -80,3 +80,3 @@ "scripts": {
     "test:prepare": "vite-node scripts/load-files.ts",
-    "test:unit": "vite-node scripts/load-files.ts && vitest",
+    "test:unit": "vitest",
     "types:build": "scalar-types-build",
@@ -83,0 +83,0 @@ "types:check": "scalar-types-check"

README.md

@@ -58,2 +58,136 @@ # Scalar OpenAPI Parser
 
+### Bundle external references
+
+The OpenAPI specification allows to point to external files (URLs or files). But sometimes, you just want to combine all files into one.
+
+#### Plugins
+
+##### fetchUrls
+This plugins handles all external urls. It works for both node.js and browser environment
+
+```ts
+import { bundle, fetchUrls } from '@scalar/openapi-parser'
+
+const document = {
+  openapi: '3.1.0',
+  info: { title: 'Bundled API', version: '1.0.0' },
+  paths: {},
+  components: {
+    schemas: {
+      User: { $ref: 'https://example.com/user-schema.json#' }
+    }
+  }
+}
+
+// This will bundle all external documents and turn all references from external into internal
+await bundle(document, {
+  plugins: [fetchUrls()],
+  treeShake: true  // <------  This flag will try to remove any unused part of the external document
+})
+
+console.log(document)
+```
+
+###### Limiting the number of concurrent requests
+
+```ts
+await bundle(document, {
+  plugins: [
+    fetchUrls({
+      limit: 10, // it should run at most 10 requests at the same time
+    }),
+  ],
+  treeShake: false
+})
+
+```
+
+###### Custom headers
+To pass custom headers to requests for specific domains you can configure the fetch plugin like the example
+
+```ts
+await bundle(
+  document,
+  {
+    plugins: [
+      fetchUrls({
+        // Pass custom headers
+        // The header will only be attached to the list of domains
+        headers: [
+          {
+            domains: ['example.com'],
+            headers: {
+              'Authorization': 'Bearer <TOKEN>'
+            }
+          }
+        ]
+      }),
+      readFiles(),
+    ],
+    treeShake: false
+  },
+)
+```
+
+###### Bundle from remote url
+
+```ts
+const result = await bundle(
+  'https://example.com/openapi.json',
+  {
+    plugins: [
+      fetchUrls(),
+    ],
+    treeShake: false
+  },
+)
+
+// Bundled document
+console.log(result)
+```
+
+##### readFiles
+This plugins handles local files. Only works on node.js environment
+
+```ts
+import { bundle, readFiles } from '@scalar/openapi-parser'
+
+const document = {
+  openapi: '3.1.0',
+  info: { title: 'Bundled API', version: '1.0.0' },
+  paths: {},
+  components: {
+    schemas: {
+      User: { $ref: './user-schema.json#' }
+    }
+  }
+}
+
+// This will bundle all external documents and turn all references from external into internal
+await bundle(document, {
+  plugins: [readFiles()],
+  treeShake: false
+})
+
+console.log(document)
+```
+
+###### Bundle from local file
+You can pass the file path directly but make sure to have the correct plugins to handle reading from the local files
+
+```ts
+const result = await bundle(
+  './input.json',
+  {
+    plugins: [
+      readFiles(),
+    ],
+    treeShake: false
+  },
+)
+
+// Bundled document
+console.log(result)
+```
+
 ### Track references
@@ -60,0 +194,0 @@

No alert changes

Improved metrics

Total package byte prevSize

814181

7.78%

Number of package files

270

8%

Lines of code

15066

4.1%

Number of lines in readme file

391

52.14%

No dependency changes