Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@shopware/api-gen) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

shopware/frontends - api-gen

Welcome to @shopware/api-gen CLI. Generate TypeScript schemas from Shopware OpenAPI specification.

After generating schemas, you can use them in fully typed API Client.

Usage

# ✨ Auto-detect
npx nypm install -D @shopware/api-gen

# npm
npm install -D @shopware/api-gen

# yarn
yarn add -D @shopware/api-gen

# pnpm
pnpm install -D @shopware/api-gen

# bun
bun install -D @shopware/api-gen

Features

Generator will create a new directory api-types with TypeScript schemas inside. Depending on the apiType parameter it will create storeApiTypes.ts or adminApiTypes.ts file.

Overriding

If your instance contains inacurate or outdated OpenAPI specification, you can override it by creating a new file inside api-types directory::

storeApiTypes.overrides.ts for store API
adminApiTypes.overrides.ts for admin API

Example of overrides file:

import { components as mainComponents } from "./storeApiTypes";

export type components = mainComponents & {
  schemas: Schemas;
};

export type Schemas = {
  CustomerAddress: {
    qwe: string;
  };
};

export type operations = {
  "myNewEndpointWithDifferentBodys post /aaaaa/bbbbb":
    | {
        contentType?: "application/json";
        accept?: "application/json";
        body: components["schemas"]["CustomerAddress"];
        response: components["schemas"]["Country"];
        responseCode: 201;
      }
    | {
        contentType: "application/xml";
        accept?: "application/json";
        body: {
          someting: boolean;
        };
        response: {
          thisIs200Response: string;
        };
        responseCode: 200;
      };
  "updateCustomerAddress patch /account/address/{addressId}": {
    contentType?: "application/json";
    accept?: "application/json";
    /**
     * We're testing overrides, assuming update address can only update the city
     */
    body: {
      city: string;
    };
    response: components["schemas"]["CustomerAddress"];
    responseCode: 200;
  };
};

Commands

add shortcut to your `package.json` scripts

{
  "scripts": {
    "generate-types": "shopware-api-gen generate --apiType=store"
  }
}

then running pnpm generate-types will generate types in api-types directory.

`generate`

Transform OpenAPI specification from JSON file to Typescript schemas. Use loadSchema command first.

options:

pnpx @shopware/api-gen generate --help

# generate schemas from store API
pnpx @shopware/api-gen generate --apiType=store

# generate schemas from admin API
pnpx @shopware/api-gen generate --apiType=admin

`loadSchema`

Load OpenAPI specification from Shopware instance and save it to JSON file.

options:

pnpx @shopware/api-gen loadSchema --help

# load schema from store API
pnpx @shopware/api-gen loadSchema --apiType=store

# load schema from admin API
pnpx @shopware/api-gen loadSchema --apiType=admin

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
SHOPWARE_ADMIN_USERNAME="my@username.com"
SHOPWARE_ADMIN_PASSWORD="my-password"

Changelog

Full changelog for stable version is available here

Latest changes: 0.0.0-canary-20240613111750

Major Changes

#871 1566f7a Thanks @patzick! - Read more about new major release: https://github.com/shopware/frontends/discussions/965

Minor Changes

#534 6170dca Thanks @patzick! - loadSchema command added by splitting generate command
#534 6170dca Thanks @patzick! - Sorting paths in the same order by api patchs
#534 6170dca Thanks @patzick! - Command generate has been splitted and doing only transformation from json to d.ts file

#564 93a6048 Thanks @patzick! - Added apiType option in loadSchema command. With SHOPWARE_ADMIN_USERNAME and SHOPWARE_ADMIN_PASSWORD env variables we can now authorize Admin API schema.

example:

# load schema from store API
pnpx @shopware/api-gen loadSchema --apiType=store --filename=storeApiSchema.json

# load schema from admin API
pnpx @shopware/api-gen loadSchema --apiType=admin --filename=adminApiSchema.json

#903 18d8528 Thanks @mdanilowicz! - Add Blob type support
#534 6170dca Thanks @patzick! - Schema operations is now a generic type to help with overriding types

Patch Changes

#534 6170dca Thanks @patzick! - Generated GenericRecord is more open to avoid type problems
#928 bada1cd Thanks @mdanilowicz! - Skip GenericRecord for the object with additionalProperties
Updated dependencies [1566f7a, 782ef4d, 9643e56, 1583a7a, 97d2859, d60d062, 89a97a4, 864616f]:
- @shopware/api-client@0.0.0-canary-20240613111750

@shopware/api-gen