feat: load files, add throwOnError to load

Author: hanspagel

packages/openapi-parser/src/configuration.ts

@@ -28,6 +28,7 @@ export const ERRORS = {
   INVALID_REFERENCE: 'Can’t resolve reference: %s',
   EXTERNAL_REFERENCE_NOT_FOUND: 'Can’t resolve external reference: %s',
   FILE_DOES_NOT_EXIST: 'File does not exist: %s',
+  NO_CONTENT: 'No content found',
 } as const
 
 export type VALIDATOR_ERROR = keyof typeof ERRORS

packages/openapi-parser/src/types/index.ts

@@ -12,6 +12,7 @@ export type AnyObject = Record<string, any>
 
 export type LoadResult = {
   filesystem: Filesystem
+  errors?: ErrorObject[]
 }
 
 export type ValidateResult = {

packages/openapi-parser/src/utils/load/load.test.ts

@@ -395,4 +395,26 @@ describe('load', async () => {
       },
     })
   })
+
+  it('returns an error', async () => {
+    const { errors } = await load('INVALID', {
+      plugins: [readFiles(), fetchUrls()],
+    })
+
+    expect(errors).toMatchObject([
+      {
+        code: 'EXTERNAL_REFERENCE_NOT_FOUND',
+        message: 'Can’t resolve external reference: INVALID',
+      },
+    ])
+  })
+
+  it('throws an error', async () => {
+    expect(async () => {
+      await load('INVALID', {
+        plugins: [readFiles(), fetchUrls()],
+        throwOnError: true,
+      })
+    }).rejects.toThrowError('Can’t resolve external reference: INVALID')
+  })
 })

packages/openapi-parser/src/utils/load/load.ts

@@ -1,4 +1,11 @@
-import type { Filesystem, LoadResult } from '../../types'
+import { ERRORS } from '../../configuration'
+import type {
+  AnyObject,
+  ErrorObject,
+  Filesystem,
+  LoadResult,
+  ThrowOnErrorOption,
+} from '../../types'
 import { getEntrypoint } from '../getEntrypoint'
 import { getListOfReferences } from '../getListOfReferences'
 import { makeFilesystem } from '../makeFilesystem'
@@ -18,26 +25,64 @@ export async function load(
     plugins?: LoadPlugin[]
     filename?: string
     filesystem?: Filesystem
-  },
+  } & ThrowOnErrorOption,
 ): Promise<LoadResult> {
+  const errors: ErrorObject[] = []
+
   // Don’t load a reference twice, check the filesystem before fetching something
   if (
     options?.filesystem &&
     options?.filesystem.find((entry) => entry.filename === value)
   ) {
     return {
       filesystem: options.filesystem,
+      errors,
     }
   }
 
   // Check whether the value is an URL or file path
   const plugin = options?.plugins?.find((plugin) => plugin.check(value))
-  const content = normalize(plugin ? await plugin.get(value) : value)
+
+  let content: AnyObject
+
+  if (plugin) {
+    try {
+      content = normalize(await plugin.get(value))
+    } catch (error) {
+      if (options?.throwOnError) {
+        throw new Error(
+          ERRORS.EXTERNAL_REFERENCE_NOT_FOUND.replace('%s', value),
+        )
+      }
+
+      errors.push({
+        code: 'EXTERNAL_REFERENCE_NOT_FOUND',
+        message: ERRORS.EXTERNAL_REFERENCE_NOT_FOUND.replace('%s', value),
+      })
+
+      return {
+        filesystem: [],
+        errors,
+      }
+    }
+  } else {
+    content = normalize(value)
+  }
 
   // No content
   if (content === undefined) {
+    if (options?.throwOnError) {
+      throw new Error('No content to load')
+    }
+
+    errors.push({
+      code: 'NO_CONTENT',
+      message: ERRORS.NO_CONTENT,
+    })
+
     return {
       filesystem: [],
+      errors,
     }
   }
 
@@ -56,6 +101,7 @@ export async function load(
   if (listOfReferences.length === 0) {
     return {
       filesystem,
+      errors,
     }
   }
 
@@ -79,12 +125,17 @@ export async function load(
       continue
     }
 
-    const { filesystem: referencedFiles } = await load(target, {
-      ...options,
-      // Make the filename the exact same value as the $ref
-      // TODO: This leads to problems, if there are multiple references with the same file name but in different folders
-      filename: reference,
-    })
+    const { filesystem: referencedFiles, errors: newErrors } = await load(
+      target,
+      {
+        ...options,
+        // Make the filename the exact same value as the $ref
+        // TODO: This leads to problems, if there are multiple references with the same file name but in different folders
+        filename: reference,
+      },
+    )
+
+    errors.push(...newErrors)
 
     filesystem = [
       ...filesystem,
@@ -99,5 +150,6 @@ export async function load(
 
   return {
     filesystem,
+    errors,
   }
 }

packages/openapi-parser/tests/migration-layer.json

@@ -0,0 +1,23 @@
+{
+    "openapi": "3.1.0",
+    "info": {
+      "title": "Hello World",
+      "version": "1.0.0"
+    },
+    "paths": {
+      "/foobar": {
+        "post": {
+          "requestBody": {
+            "$ref": "#/components/requestBodies/Foobar"
+          }
+        }
+      }
+    },
+    "components": {
+      "requestBodies": {
+        "Foobar": {
+          "content": {}
+        }
+      }
+    }
+  }

packages/openapi-parser/tests/migration-layer.test.ts

@@ -1,7 +1,11 @@
 import OriginalSwaggerParser from '@apidevtools/swagger-parser'
-import { describe, expect, it } from 'vitest'
+import path from 'node:path'
+import { describe, expect, it, vi } from 'vitest'
 
 import { dereference } from '../src/utils/dereference'
+import { load } from '../src/utils/load'
+import { fetchUrls } from '../src/utils/load/plugins/fetchUrls'
+import { readFiles } from '../src/utils/load/plugins/readFiles'
 import { validate } from '../src/utils/validate'
 
 const myAPI = JSON.stringify({
@@ -30,19 +34,33 @@ const myAPI = JSON.stringify({
 
 class SwaggerParser {
   static async validate(api: string, callback: (err: any, api: any) => void) {
-    validate(api, {
-      throwOnError: true,
-    })
-      .then((result) => {
-        callback(null, result.schema)
+    try {
+      const { filesystem } = await load(api, {
+        plugins: [fetchUrls(), readFiles()],
+        throwOnError: true,
       })
-      .catch((error) => {
-        callback(error, null)
+
+      validate(filesystem, {
+        throwOnError: true,
       })
+        .then((result) => {
+          callback(null, result.schema)
+        })
+        .catch((error) => {
+          callback(error, null)
+        })
+    } catch (error) {
+      callback(error, null)
+    }
   }
 
   static async dereference(api: string) {
-    return dereference(api).then((result) => result.schema)
+    const { filesystem } = await load(api, {
+      plugins: [fetchUrls(), readFiles()],
+      throwOnError: true,
+    })
+
+    return dereference(filesystem).then((result) => result.schema)
   }
 }
 
@@ -85,4 +103,38 @@ describe('dereference', () => {
     // so you can easily access any part of the API using simple dot notation
     expect(api?.paths?.['/foobar']?.post?.requestBody?.content).toEqual({})
   })
+
+  it('dereferences URLs', async () => {
+    global.fetch = async (url: string) =>
+      ({
+        text: async () => {
+          if (url === 'http://example.com/specification/openapi.yaml') {
+            return myAPI
+          }
+
+          throw new Error('Not found')
+        },
+      }) as Response
+
+    let api = await SwaggerParser.dereference(
+      'http://example.com/specification/openapi.yaml',
+    )
+
+    // The `api` object is a normal JavaScript object,
+    // so you can easily access any part of the API using simple dot notation
+    expect(api?.paths?.['/foobar']?.post?.requestBody?.content).toEqual({})
+  })
+
+  it('dereferences files', async () => {
+    const EXAMPLE_FILE = path.join(
+      new URL(import.meta.url).pathname,
+      '../../tests/migration-layer.json',
+    )
+
+    let api = await SwaggerParser.dereference(EXAMPLE_FILE)
+
+    // The `api` object is a normal JavaScript object,
+    // so you can easily access any part of the API using simple dot notation
+    expect(api?.paths?.['/foobar']?.post?.requestBody?.content).toEqual({})
+  })
 })