@shopware/api-gen 1.3.3 → 1.5.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": "https://raw.githubusercontent.com/shopware/frontends/main/packages/api-gen/api-gen.schema.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": "./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"
+    ]
+  }
 }
 ```
 
@@ -223,11 +252,22 @@ Remember to add `.env` file in order to authenticate with Shopware instance.
 OPENAPI_JSON_URL="https://your-shop-instance.shopware.store"
 ## This one needed to fetch store API schema
 OPENAPI_ACCESS_KEY="YOUR_STORE_API_ACCESS_KEY"
-## These two needed to fetch admin API schema
+
+## Admin API authentication (choose one method):
+
+## Option 1: Password grant (username/password)
 SHOPWARE_ADMIN_USERNAME="my@username.com"
 SHOPWARE_ADMIN_PASSWORD="my-password"
+
+## Option 2: Client credentials grant (integration)
+## Create an integration in Shopware Admin > Settings > System > Integrations
+# SHOPWARE_ADMIN_CLIENT_ID="your-integration-client-id"
+# SHOPWARE_ADMIN_CLIENT_SECRET="your-integration-secret"
 ```
 
+> [!NOTE]
+> When `SHOPWARE_ADMIN_CLIENT_SECRET` is set, the client credentials grant will be used automatically. Otherwise, the password grant with username/password is used.
+
 ### `validateJson`
 
 This command allow to validate the output JSON file of your instance. You can configure which rules should be applied, we provide you with the schema configuration file, so you can easily modify it.
@@ -245,16 +285,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 +373,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 +401,13 @@ 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.3
+### Latest changes: 1.5.0
+
+### Minor Changes
+
+- [#2262](https://github.com/shopware/frontends/pull/2262) [`7a20ea0`](https://github.com/shopware/frontends/commit/7a20ea0454ee237c772e532a03408477e968a958) Thanks [@mkucmus](https://github.com/mkucmus)! - Added support for `client_credentials` grant type authentication when loading Admin API schema. Set `SHOPWARE_ADMIN_CLIENT_SECRET` and `SHOPWARE_ADMIN_CLIENT_ID`environment variables to use integration credentials instead of username/password.
 
 ### Patch Changes
 
-- [#1942](https://github.com/shopware/frontends/pull/1942) [`a344abb`](https://github.com/shopware/frontends/commit/a344abba579c91c4f775e7be27ed882ca420fdc2) Thanks [@patzick](https://github.com/patzick)! - Allow shared parameters to be available in schema resolver.
+- Updated dependencies [[`9604f22`](https://github.com/shopware/frontends/commit/9604f22678150d04c3c3156fd8ee2ce440c8c8bf), [`b5f7e2a`](https://github.com/shopware/frontends/commit/b5f7e2a20c9dfdde1690e9006252d847f732bc0a), [`9604f22`](https://github.com/shopware/frontends/commit/9604f22678150d04c3c3156fd8ee2ce440c8c8bf)]:
+  - @shopware/api-client@1.5.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" }]
+    }
+  }
+}