@shopware/api-gen 1.3.2 → 1.4.0

package/README.md

@@ -5,8 +5,6 @@ Generate TypeScript schemas from Shopware OpenAPI specification.
 
 After generating schemas, you can use them in fully typed [API Client](https://www.npmjs.com/package/@shopware/api-client).
 
-To take a deep dive into the topic visit the [🧑‍🎓 API Client Tutorial](https://api-client-tutorial-composable-frontends.pages.dev) first.
-
 ## Usage
 
 <!-- automd:pm-install name="@shopware/api-gen" dev -->
@@ -106,24 +104,55 @@ export type operations = {
 There is a possiblity to add patches (partial overrides) to the schema. Partial overrides are applied directly to the JSON schema, so the syntax needs to be correct. It can then be used by the backend CI tool to validate and apply these patches directly to the schema to fix inconsistencies.
 
 By default CLI is fetching the patches from the api-client repository, but you can provide your own patches file by adding a path to the `api-gen.config.json` file.
-Example:
+
+### API-specific configuration (Recommended)
+
+You can configure patches and rules separately for Store API and Admin API:
+
+```json
+{
+  "$schema": "./node_modules/@shopware/api-gen/api-gen.schema.json",
+  "store-api": {
+    "patches": [
+      "storeApiSchema.overrides.json",
+      "./api-types/myStoreApiPatches.json"
+    ],
+    "rules": ["COMPONENTS_API_ALIAS"]
+  },
+  "admin-api": {
+    "patches": ["adminApiSchema.overrides.json"],
+    "rules": ["COMPONENTS_API_ALIAS"]
+  }
+}
+```
+
+This allows you to maintain different configurations for each API type.
+
+### Legacy configuration (Deprecated)
+
+The root-level `patches` and `rules` properties are deprecated but still supported for backwards compatibility:
 
 ```json
 {
-  "$schema": "https://raw.githubusercontent.com/shopware/frontends/main/packages/api-gen/api-gen.schema.json",
+  "$schema": "./node_modules/@shopware/api-gen/api-gen.schema.json",
   "patches": ["storeApiTypes.overrides.json"]
 }
 ```
 
-or you could use multiple patches and add your own overrides on top:
+> [!WARNING]
+> Root-level `patches` and `rules` are deprecated. Please migrate to the API-specific configuration (`store-api` or `admin-api`).
+
+You could also use multiple patches and add your own overrides on top:
 
 ```json
 {
-  "$schema": "https://raw.githubusercontent.com/shopware/frontends/main/packages/api-gen/api-gen.schema.json",
-  "patches": [
-    "https://raw.githubusercontent.com/shopware/frontends/refs/heads/main/packages/api-client/api-types/storeApiSchema.overrides.json",
-    "./api-types/myOwnPatches.overrides.json"
-  ]
+  "$schema": "./node_modules/@shopware/api-gen/api-gen.schema.json",
+  "store-api": {
+    "patches": [
+      "./node_modules/@shopware/api-client/api-types/storeApiSchema.overrides.json",
+      "./api-types/myOwnPatches.overrides.json"
+    ]
+  }
 }
 ```
 
@@ -245,16 +274,50 @@ this searches for `api-types/storeApiTypes.json` file and validates it. Use [loa
 
 Prepare your config file named **api-gen.config.json**:
 
-```JSON
+```json
 {
-  "$schema": "https://raw.githubusercontent.com/shopware/frontends/main/packages/api-gen/api-gen.schema.json",
-  "rules": [
-    "COMPONENTS_API_ALIAS" // you have description on autocompletion what specific rule does, this one for example ensures correctness of the apiAlias field
-  ],
-  //"patches": "storeApiTypes.overrides.json" // -> path to your overrides file in api-types folder, default is fetched from api-client repository
+  "$schema": "./node_modules/@shopware/api-gen/api-gen.schema.json",
+  "store-api": {
+    "rules": ["COMPONENTS_API_ALIAS"],
+    "patches": ["storeApiSchema.overrides.json"]
+  },
+  "admin-api": {
+    "rules": ["COMPONENTS_API_ALIAS"],
+    "patches": ["adminApiSchema.overrides.json"]
+  }
 }
 ```
 
+> [!NOTE]
+> The `rules` configuration is API-type specific. When running `validateJson --apiType=store`, only the rules defined in `store-api.rules` will be applied.
+
+### `split` - Experimental
+
+Split an OpenAPI schema into multiple files, organized by tags or paths. This is useful for breaking down a large schema into smaller, more manageable parts.
+
+The main reason for this is that the complete JSON schema can be too large and complex for API clients like Postman or Insomnia to handle, sometimes
+causing performance issues or import failures due to the file size or circular references. This command helps developers to extract only the parts of
+the schema they need and then import it to the API client of their choice.
+
+Example usage:
+
+```bash
+# Display all available tags
+pnpx @shopware/api-gen split <path-to-schema-file> --list tags
+
+# Display all available paths
+pnpx @shopware/api-gen split <path-to-schema-file> --list paths
+
+# Split schema by tags and show detailed linting errors
+pnpx @shopware/api-gen split <path-to-schema-file> --splitBy=tags --outputDir <output-directory> --verbose-linting
+
+# Split schema by a single tag
+pnpx @shopware/api-gen split <path-to-schema-file> --splitBy=tags --outputDir <output-directory> --filterBy "media"
+
+# Split schema by a single path
+pnpx @shopware/api-gen split <path-to-schema-file> --splitBy=paths --outputDir <output-directory> --filterBy "/api/_action/media/{mediaId}/upload"
+```
+
 ### Programmatic usage
 
 Each command can also be used programmatically within your own scripts:
@@ -299,16 +362,27 @@ await validateJson({
 });
 ```
 
+#### `split`
+
+```ts
+import { split } from "@shopware/api-gen";
+
+await split({
+  schemaFile: "path/to/your/schema.json",
+  outputDir: "path/to/output/directory",
+  splitBy: "tags", // or "paths"
+  // filterBy: "TagName" // optional filter
+});
+```
+
 > [!NOTE]  
 > Make sure that the required environment variables are set for the node process when executing commands programmatically.
 
 ## Links
 
-- [🧑‍🎓 Tutorial](https://api-client-tutorial-composable-frontends.pages.dev)
-
 - [📘 Documentation](https://frontends.shopware.com)
 
-- [👥 Community Slack](https://shopwarecommunity.slack.com) (`#composable-frontends` channel)
+- [👥 Community Discord](https://discord.com/channels/1308047705309708348/1405501315160739951) (`#composable-frontend` channel)
 
 <!-- AUTO GENERATED CHANGELOG -->
 
@@ -316,8 +390,35 @@ await validateJson({
 
 Full changelog for stable version is available [here](https://github.com/shopware/frontends/blob/main/packages/api-gen/CHANGELOG.md)
 
-### Latest changes: 1.3.2
+### Latest changes: 1.4.0
+
+### Minor Changes
+
+- [#2181](https://github.com/shopware/frontends/pull/2181) [`ed72205`](https://github.com/shopware/frontends/commit/ed72205853e9fc40db513f8a4d08acf2dd7b1fba) Thanks [@patzick](https://github.com/patzick)! - Add API-specific configuration support for `store-api` and `admin-api` in `api-gen.config.json`. This allows configuring `rules` and `patches` separately for each API type. Root-level `rules` and `patches` are now deprecated but still supported for backwards compatibility.
+
+  Example:
+
+  ```json
+  {
+    "$schema": "./node_modules/@shopware/api-gen/api-gen.schema.json",
+    "store-api": {
+      "patches": ["storeApiSchema.overrides.json"],
+      "rules": ["COMPONENTS_API_ALIAS"]
+    },
+    "admin-api": {
+      "patches": ["adminApiSchema.overrides.json"]
+    }
+  }
+  ```
+
+- [#2126](https://github.com/shopware/frontends/pull/2126) [`e595bc1`](https://github.com/shopware/frontends/commit/e595bc1ea6afe01a0065300277a78ef8c1fe5667) Thanks [@mdanilowicz](https://github.com/mdanilowicz)! - Enhanced OpenAPI schema override merging to properly handle conflicts between `$ref` and composition keywords (`oneOf`, `anyOf`, `allOf`, `not`). When merging overrides:
+  - Composition keywords now automatically remove conflicting `$ref` properties
+  - `$ref` overrides can replace composition keywords entirely
+  - Different composition keywords can replace each other (e.g., `allOf` → `oneOf`)
+
+  This ensures correct schema merging when using composition keywords in override files, preventing invalid OpenAPI schemas with conflicting `$ref` and composition keyword properties.
 
 ### Patch Changes
 
-- [#1939](https://github.com/shopware/frontends/pull/1939) [`cb62cfb`](https://github.com/shopware/frontends/commit/cb62cfb541552ce4e0dc8a02a7a8bddb72ef4de1) Thanks [@patzick](https://github.com/patzick)! - Update typescript version to match openapi-typescript version, causing problems with generating proper schema.
+- Updated dependencies [[`70dcf95`](https://github.com/shopware/frontends/commit/70dcf95d4370c63964d877a5cab113a53f93ca19), [`c77daa6`](https://github.com/shopware/frontends/commit/c77daa6a11e96c7f3688b16f7da010b54c7f5e8b)]:
+  - @shopware/api-client@1.4.0

package/api-gen.schema.json

@@ -0,0 +1,99 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "$defs": {
+    "patchSource": {
+      "type": "string",
+      "anyOf": [
+        {
+          "format": "url"
+        },
+        {
+          "format": "file-path"
+        },
+        {
+          "const": "storeApiSchema.overrides.json",
+          "description": "Clean core Store API Schema patches"
+        },
+        {
+          "const": "storeApiSchema.b2b.overrides.json",
+          "description": "B2B module patches"
+        },
+        {
+          "const": "adminApiSchema.overrides.json",
+          "description": "Admin API Schema patches"
+        }
+      ]
+    },
+    "rulesArray": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "anyOf": [
+          {
+            "const": "COMPONENTS_API_ALIAS",
+            "description": "Enforce proper apiAlias fields on components"
+          }
+        ]
+      }
+    },
+    "patchesConfig": {
+      "oneOf": [
+        {
+          "$ref": "#/$defs/patchSource"
+        },
+        {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/patchSource"
+          }
+        }
+      ]
+    },
+    "apiTypeConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "rules": {
+          "description": "Validation rules to apply for this API type",
+          "allOf": [{ "$ref": "#/$defs/rulesArray" }]
+        },
+        "patches": {
+          "description": "Path to a file or files containing patches to apply to the schema",
+          "allOf": [{ "$ref": "#/$defs/patchesConfig" }]
+        }
+      }
+    }
+  },
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "anyOf": [
+        {
+          "format": "url"
+        },
+        {
+          "format": "file-path"
+        }
+      ]
+    },
+    "store-api": {
+      "description": "Configuration specific to Store API type generation",
+      "allOf": [{ "$ref": "#/$defs/apiTypeConfig" }]
+    },
+    "admin-api": {
+      "description": "Configuration specific to Admin API type generation",
+      "allOf": [{ "$ref": "#/$defs/apiTypeConfig" }]
+    },
+    "rules": {
+      "deprecated": true,
+      "description": "DEPRECATED: Use 'store-api.rules' or 'admin-api.rules' instead.",
+      "allOf": [{ "$ref": "#/$defs/rulesArray" }]
+    },
+    "patches": {
+      "deprecated": true,
+      "description": "DEPRECATED: Use 'store-api.patches' or 'admin-api.patches' instead.",
+      "allOf": [{ "$ref": "#/$defs/patchesConfig" }]
+    }
+  }
+}