Improve error message for parsing failure

Author: AdrianMachado

apps/api/src/lib/validate-openapi.spec.ts

@@ -19,7 +19,7 @@ describe("Validate OpenAPI", function () {
         }`,
       fileExtension: "json",
     });
-    assert.isTrue(result);
+    assert.isTrue(result.isValid);
   });
 
   it("Validates file falsy", async function () {
@@ -35,6 +35,6 @@ describe("Validate OpenAPI", function () {
       }`,
       fileExtension: "json",
     });
-    assert.isFalse(result);
+    assert.isFalse(result.isValid);
   });
 });

apps/api/src/lib/validate-openapi.ts

@@ -1,12 +1,12 @@
-import { ApiError, Problems } from "@zuplo/errors";
+import { ProblemDetails, Problems } from "@zuplo/errors";
 import { load } from "js-yaml";
 import { OpenApiFileExtension } from "./types.js";
 import spectralCore, { Document } from "@stoplight/spectral-core";
 import SpectralParsers from "@stoplight/spectral-parsers";
 
 export const checkFileIsJsonOrYaml = (
   fileContentString: string,
-): OpenApiFileExtension => {
+): OpenApiFileExtension | ProblemDetails => {
   try {
     JSON.parse(fileContentString);
     return "json";
@@ -21,16 +21,16 @@ export const checkFileIsJsonOrYaml = (
     // Ignore
   }
 
-  throw new ApiError({
+  return {
     ...Problems.BAD_REQUEST,
     detail: "Invalid file format. Only JSON and YAML are supported.",
-  });
+  };
 };
 
 const validateOpenapi = (options: {
   fileContent: string;
   fileExtension: string;
-}) => {
+}): { isValid: true } | { isValid: false; error: ProblemDetails } => {
   const parser =
     options.fileExtension === "json"
       ? SpectralParsers.Json
@@ -44,27 +44,43 @@ const validateOpenapi = (options: {
       options.fileExtension,
     );
   } catch (err) {
-    throw new ApiError({
-      ...Problems.BAD_REQUEST,
-      detail: "Could not parse OpenAPI file. Possible syntax error.",
-    });
+    return {
+      isValid: false,
+      error: {
+        ...Problems.BAD_REQUEST,
+        detail: "Could not parse OpenAPI file. Possible syntax error.",
+      },
+    };
   }
 
-  // TODO: clean this up
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const openAPIFileVersion = (openApiSpectralDoc.data as any)?.openapi || "";
+  const openAPIFileVersion = (openApiSpectralDoc.data as any)?.openapi;
 
   if (!openAPIFileVersion) {
     // if no version is specified, assume it's a swagger file
-    return false;
+    return {
+      isValid: false,
+      error: {
+        ...Problems.BAD_REQUEST,
+        detail: "No OpenAPI version specified. Only OpenAPI v3.x is supported.",
+      },
+    };
   }
 
   const validVersionExists =
     ["3.0.0", "3.0.1", "3.0.2", "3.0.3", "3.1.0"].find((version) =>
       openAPIFileVersion.includes(version),
     ) !== undefined;
-
-  return validVersionExists;
+  if (!validVersionExists) {
+    return {
+      isValid: false,
+      error: {
+        ...Problems.BAD_REQUEST,
+        detail: `Invalid OpenAPI version. Only OpenAPI v3.x is supported. Found: ${openAPIFileVersion}.`,
+      },
+    };
+  }
+  return { isValid: true };
 };
 
 export default validateOpenapi;

apps/api/src/routes/upload.ts

@@ -105,22 +105,26 @@ export async function parseMultipartUpload(
   if (!fileContent) {
     throw new ApiError({
       ...Problems.BAD_REQUEST,
-      detail: "Invalid request body, no file content",
+      detail: `Invalid request body, no file content. Uploader: ${email}.`,
     });
   }
   const fileContentString = fileContent.toString();
 
   const fileIsJsonOrYamlResult = checkFileIsJsonOrYaml(fileContentString);
-
-  if (
-    !validateOpenapi({
-      fileContent: fileContentString,
-      fileExtension: fileIsJsonOrYamlResult,
-    })
-  ) {
+  if (typeof fileIsJsonOrYamlResult !== "string") {
     throw new ApiError({
-      ...Problems.BAD_REQUEST,
-      detail: "Invalid OpenAPI version. Only OpenAPI v3.x is supported.",
+      ...fileIsJsonOrYamlResult,
+      detail: `${fileIsJsonOrYamlResult.detail} Uploader: ${email}.`,
+    });
+  }
+  const openApiValidationResult = validateOpenapi({
+    fileContent: fileContentString,
+    fileExtension: fileIsJsonOrYamlResult,
+  });
+  if (!openApiValidationResult.isValid) {
+    throw new ApiError({
+      ...openApiValidationResult.error,
+      detail: `${openApiValidationResult.error.detail} Uploader: ${email}. File extension: ${fileIsJsonOrYamlResult}.`,
     });
   }