Generate custom API Client for Shopware 6

Cover image for Generate custom API Client for Shopware 6
1/24/2024

Why?

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.

Requirements

Process to generate Schema for store API Client

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 Client

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?

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’s

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

Example results.html page with oasdiff, to compare json schema files

Known Issues

  • 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.
Comments 💬 & Reactions ✨