Generate custom API Client for Shopware 6

Why?Link to this section#

With Composable Frontends, you can create your own JavaScript/Typescript based API Client from your local or online running Shopware 6 Instance. This brings you the advantage that all Custom Endpoints are also included in the API Client if they have a proper OpenAPI Schema definition. In this post, I describe how and what steps are needed to do so. There will also be another blog post about how to extend the paths and operations manually.

RequirementsLink to this section#

• A running Shopware 6 Instance (local or online)
• A cloned Composable Frontends Repository

Process to generate Schema for store API ClientLink to this section#

Steps to generate storeApiSchema.json and storeApiSchema.d.ts files

• From your Frontends Repository folder go into this sub-folder packages/api-gen
• Make sure your API schema JSON file is reachable
  (e.g. http://127.0.0.1:8000/store-api/_info/openapi3.json)
• Create a .env File with these values:

  OPENAPI_JSON_URL=“http://127.0.0.1:8000” OPENAPI_ACCESS_KEY=“YOUR_ACCESS_KEY”

• Download the schema file with this command (executed in the api-gen folder):

  pnpm cli loadSchema —apiType=store —filename=storeApiSchema.json

  Now there should be a new file in packages/api-gen/storeApiSchema.json
• Create the types from the downloaded schema file with that command:

  pnpm cli generate —filename=storeApiSchema.json

  Now there should be a new file in packages/api-gen/storeApiSchema.d.ts (better rename to customStoreApiTypes-6.5.8.3.d.ts, including your Shopware Version number)

Now you can import your custom operations and paths in code like this:

import type {
  operationPaths,
  operations,
  components,
} from "../path/to/your/file/storeApiSchema";

Process to generate Schema for admin API ClientLink to this section#

Steps to generate adminApiSchema.json and adminApiSchema.d.ts files

• From your Frontends Repository folder go into this sub-folder packages/api-gen
• Make sure your API schema JSON file is reachable
  (e.g. http://127.0.0.1:8000/api/_info/openapi3.json)
• Create a .env File with these values:

  OPENAPI_JSON_URL=“http://127.0.0.1:8000” SHOPWARE_ADMIN_USERNAME=“admin” SHOPWARE_ADMIN_PASSWORD=“shopware”

• Download the schema file with this command (executed in the api-gen folder):

  pnpm cli loadSchema —apiType=admin —filename=adminApiSchema.json

  Now there should be a new file in packages/api-gen/adminApiSchema.json
• Create the types from the downloaded schema file with that command:

  pnpm cli generate —filename=adminApiSchema.json

  Now there should be a new file in packages/api-gen/adminApiSchema.d.ts (better rename to customAdminApiTypes-6.5.8.3.d.ts, including your Shopware Version number)

Now you can import your custom operations and paths in code like this:

import type {
  operationPaths,
  operations,
  components,
} from "../path/to/your/file/adminApiSchema";

You do not want to generate your own Schema Files?Link to this section#

Just use the ones that are provided via the API Client package.

For store API:

import type {
  operationPaths,
  operations,
  components,
} from "@shopware/api-client/api-types";

For admin API:

import type {
  operationPaths,
  operations,
  components,
} from "@shopware/api-client/admin-api-types";

Compare OpenAPI Schema’sLink to this section#

Steps to compare new and old apiSchema files to see the changes between versions for example.

• Make sure you have Golang installed and it is working in your terminal (export path)
• We will use oasdiff to compare the OpenAPI schema JSON files
• Install oasdiff with this command:

  go install github.com/tufin/oasdiff@latest

• Create two different apiSchema.json files for example one for Shopware 6.6. and one for Shopware 6.5 (see generate steps above)
• Now execute this diff command where the two different JSON files are located:

  oasdiff diff apiSchema-before.json apiSchema.json -f html > result.html

• Now you can open the result.html in your browser and look through the changes.

Example how the result.html Page will look like

Known IssuesLink to this section#

• Do not use this CLI command for generating the schema JSON file:

  bin/console framework:schema -s openapi3 —store-api apiSchema.json

  Because the component’s schema definitions are missing.