feat(api-gen): allow multiple json overrides for schema

.changeset/tidy-otters-know.md

@@ -0,0 +1,5 @@
+---
+"@shopware/api-gen": minor
+---
+
+Possibility to add multiple override json patches. Now you can use our default overrides and add your own on top of it.

packages/api-client/api-gen.config.json

@@ -1,4 +1,5 @@
 {
   "$schema": "../api-gen/api-gen.schema.json",
-  "rules": ["COMPONENTS_API_ALIAS"]
+  "rules": ["COMPONENTS_API_ALIAS"],
+  "patches": ["./api-types/storeApiSchema.overrides.json"]
 }

packages/api-gen/README.md

@@ -107,7 +107,18 @@ Example:
 
 ```json
 {
-  "patches": "./api-types/storeApiTypes.overrides.json"
+  "patches": ["./api-types/storeApiTypes.overrides.json"]
+}
+```
+
+or you could use multiple patches and add your own overrides on top:
+
+```json
+{
+  "patches": [
+    "https://raw.githubusercontent.com/shopware/frontends/refs/heads/main/packages/api-client/api-types/storeApiSchema.overrides.json",
+    "./api-types/myOwnPatches.overrides.json"
+  ]
 }
 ```
 
@@ -175,6 +186,11 @@ pnpx @shopware/api-gen generate --apiType=store
 pnpx @shopware/api-gen generate --apiType=admin
 ```
 
+flags:
+
+- `--debug` - display debug logs and additional information which can be helpful in case of issues
+- `--logPatches` - display patched logs, useful when you want to fix schema in original file
+
 ### `loadSchema`
 
 Load OpenAPI specification from Shopware instance and save it to JSON file.
@@ -191,6 +207,11 @@ pnpx @shopware/api-gen loadSchema --apiType=store
 pnpx @shopware/api-gen loadSchema --apiType=admin
 ```
 
+flags:
+
+- `--debug` - display debug logs and additional information which can be helpful in case of issues
+- `--logPatches` - display patched logs, useful when you want to fix schema in original file
+
 Remember to add `.env` file in order to authenticate with Shopware instance.
 
 ```bash

packages/api-gen/api-gen.schema.json

@@ -26,14 +26,32 @@
       }
     },
     "patches": {
-      "type": "string",
-      "description": "Path to a file containing patches to apply to the schema",
-      "anyOf": [
+      "description": "Path to a file or files containing patches to apply to the schema",
+      "oneOf": [
         {
-          "format": "url"
+          "type": "string",
+          "anyOf": [
+            {
+              "format": "url"
+            },
+            {
+              "format": "file-path"
+            }
+          ]
         },
         {
-          "format": "file-path"
+          "type": "array",
+          "items": {
+            "type": "string",
+            "anyOf": [
+              {
+                "format": "url"
+              },
+              {
+                "format": "file-path"
+              }
+            ]
+          }
         }
       ]
     }

packages/api-gen/src/cli.ts

@@ -44,6 +44,11 @@ yargs(hideBin(process.argv))
           default: false,
           describe: "show debug information and generate intermediate files",
         })
+        .option("logPatches", {
+          type: "boolean",
+          default: false,
+          describe: "show patched logs",
+        })
         .help();
     },
     async (args) => generate(args),
@@ -84,6 +89,16 @@ yargs(hideBin(process.argv))
           describe:
             "name of the schema json file. The default (based on apiType parameter) is 'storeApiSchema.json' or 'adminApiSchema.json'",
         })
+        .option("logPatches", {
+          type: "boolean",
+          default: false,
+          describe: "show patched logs",
+        })
+        .positional("debug", {
+          type: "boolean",
+          default: false,
+          describe: "show debug information and generate intermediate files",
+        })
         .help();
     },
     async (args) => validateJson(args),

packages/api-gen/src/commands/generate.ts

@@ -28,6 +28,7 @@ export async function generate(args: {
   filename?: string;
   apiType: "store" | "admin";
   debug: boolean;
+  logPatches: boolean;
 }) {
   const inputFilename = args.filename
     ? args.filename
@@ -72,10 +73,26 @@ export async function generate(args: {
         silent: true, // we allow to not have the config file in this command
       });
       const jsonOverrides = await loadJsonOverrides({
-        path: configJSON?.patches,
+        paths: configJSON?.patches,
         apiType: args.apiType,
       });
 
+      if (args.debug) {
+        // save overrides to file
+        const overridesFilePath = join(
+          args.cwd,
+          "api-types",
+          `${args.apiType}ApiTypes.overrides-result.json`,
+        );
+        writeFileSync(
+          overridesFilePath,
+          json5.stringify(jsonOverrides, null, 2),
+        );
+        console.log(
+          `Check the overrides result in: ${c.bold(overridesFilePath)} file.`,
+        );
+      }
+
       const {
         patchedSchema,
         todosToFix,
@@ -93,6 +110,7 @@ export async function generate(args: {
         todosToFix,
         outdatedPatches,
         alreadyApliedPatches,
+        displayPatchedLogs: args.logPatches,
       });
 
       if (args.debug) {

packages/api-gen/src/commands/validateJson.ts

@@ -1,4 +1,4 @@
-import { readFileSync } from "node:fs";
+import { readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import json5 from "json5";
 import type { ObjectSubtype, OpenAPI3 } from "openapi-typescript";
@@ -47,6 +47,8 @@ export async function validateJson(args: {
   cwd: string;
   filename?: string;
   apiType: string;
+  logPatches: boolean;
+  debug: boolean;
 }) {
   const schemaFilenameToValidate = args.filename
     ? args.filename
@@ -89,10 +91,22 @@ export async function validateJson(args: {
 
   const errors: string[] = [];
   const jsonOverrides = await loadJsonOverrides({
-    path: configJSON.patches,
+    paths: configJSON.patches,
     apiType: args.apiType,
   });
 
+  if (args.debug) {
+    const overridesFilePath = join(
+      args.cwd,
+      "api-types",
+      `${args.apiType}ApiTypes.overrides-result.json`,
+    );
+    writeFileSync(overridesFilePath, json5.stringify(jsonOverrides, null, 2));
+    console.log(
+      `Check the overrides result in: ${c.bold(overridesFilePath)} file.`,
+    );
+  }
+
   for (const [schemaName, schema] of Object.entries(
     fileContentAsJson.components?.schemas || {},
   )) {
@@ -185,6 +199,7 @@ export async function validateJson(args: {
     errors,
     outdatedPatches,
     alreadyApliedPatches,
+    displayPatchedLogs: args.logPatches,
   });
 
   console.log(

packages/api-gen/src/jsonOverrideUtils.ts

@@ -2,7 +2,7 @@ import { existsSync, readFileSync } from "node:fs";
 import json5 from "json5";
 import { ofetch } from "ofetch";
 import c from "picocolors";
-import type { OverridesSchema } from "./patchJsonSchema";
+import { type OverridesSchema, extendedDefu } from "./patchJsonSchema";
 import type { validationRules } from "./validation-rules";
 
 export type ApiGenConfig = {
@@ -44,11 +44,36 @@ function isURL(str: string) {
   return str.startsWith("http");
 }
 
+async function resolveSinglePath(pathToResolve: string) {
+  try {
+    if (isURL(pathToResolve)) {
+      const response = await ofetch(pathToResolve, {
+        responseType: "json",
+        parseResponse: json5.parse,
+      });
+      return response;
+    }
+
+    const jsonOverridesFile = await readFileSync(pathToResolve, {
+      encoding: "utf-8",
+    });
+    return json5.parse(jsonOverridesFile);
+  } catch (error) {
+    console.warn(
+      c.yellow(
+        `Problem with resolving overrides "patches" at address ${pathToResolve}. Check whether you configured it properly in your ${API_GEN_CONFIG_FILENAME}\n`,
+      ),
+      error,
+    );
+    return {};
+  }
+}
+
 export async function loadJsonOverrides({
-  path,
+  paths,
   apiType,
 }: {
-  path?: string;
+  paths?: string | string[];
   apiType: string;
 }): Promise<OverridesSchema | undefined> {
   const localPath = `./api-types/${apiType}ApiSchema.overrides.json`;
@@ -57,30 +82,37 @@ export async function loadJsonOverrides({
     ? localPath
     : `https://raw.githubusercontent.com/shopware/frontends/main/packages/api-client/api-types/${apiType}ApiSchema.overrides.json`;
 
-  const pathToResolve = path || fallbackPath;
-  console.log("Loading overrides from:", pathToResolve);
+  const patchesToResolve: string[] = Array.isArray(paths)
+    ? paths
+    : paths
+      ? [paths]
+      : [];
 
-  try {
-    if (isURL(pathToResolve)) {
-      const response = await ofetch(pathToResolve, {
-        responseType: "json",
-        parseResponse: json5.parse,
-      });
-      return response;
-    }
+  if (!patchesToResolve?.length) {
+    patchesToResolve.push(fallbackPath);
+  }
 
-    const jsonOverridesFile = await readFileSync(pathToResolve, {
-      encoding: "utf-8",
-    });
-    const content = json5.parse(jsonOverridesFile);
-    return content;
+  console.log("Loading overrides from:", patchesToResolve);
+
+  try {
+    const results = await Promise.allSettled(
+      patchesToResolve.map(resolveSinglePath),
+    );
+    // merge results from correctly settled promises
+    return extendedDefu(
+      {},
+      ...results
+        .filter((result) => result.status === "fulfilled")
+        .map((result) => result.value),
+    );
   } catch (error) {
     console.warn(
       c.yellow(
-        `Problem with resolving overrides "patches" at address ${pathToResolve}. Check whether you configuret it properly in your ${API_GEN_CONFIG_FILENAME}\n`,
+        `Problem with resolving overrides "patches". Check whether you configured it properly in your ${API_GEN_CONFIG_FILENAME}\n`,
       ),
       error,
     );
+    return {};
   }
 }
 
@@ -89,13 +121,15 @@ export function displayPatchingSummary({
   outdatedPatches,
   alreadyApliedPatches,
   errors,
+  displayPatchedLogs,
 }: {
   todosToFix: string[][];
   outdatedPatches: string[][];
   alreadyApliedPatches: number;
   errors?: string[];
+  displayPatchedLogs?: boolean;
 }) {
-  if (!errors?.length && todosToFix.length) {
+  if (displayPatchedLogs && !errors?.length && todosToFix.length) {
     console.log(c.yellow("Warnings to fix in the schema:"));
     for (const todo of todosToFix) {
       console.log(`${c.yellow("WARNING")}: ${todo[0]}`);