Logo BrocksiNet

BrocksiNet

Try to clean the web

Generate custom API Client for Shopware 6

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 API Client

Steps to generate apiSchema.json and apiSchema.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/store-api/_info/openapi3.json>" OPENAPI_ACCESS_KEY="YOURSUPERSECRETACCESSKEYFROMADMIN"
  • Download the schema file with this command (executed in the api-gen folder):
    pnpm cli loadSchema --filename=apiSchema.json
    Now there should be a new file in packages/api-gen/apiSchema.json
  • Create the types from the downloaded schema file with that command:
    pnpm cli generate --filename=apiSchema.json
    Now there should be a new file in packages/api-gen/apiSchema.d.ts
    (better rename to customApiTypes-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/apiSchema";

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

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.
Released - 24.01.2024

Comments


About the author

Bild Bjoern
Björn MeyerSoftware Engineer
Björn is interested in the details of web technologies. He started with Joomla, Drupal, Typo3, vBulletin, Fireworks and Photoshop. Today his focus is on PHP for example with Magento 2, Shopware 6 and Symfony. He also likes JavaScript with Angular, React, VueJs and TypeScript. In his free time, he seeks constant balance with swimming, running and yoga.