You're Invited:Meet the Socket Team at BlackHat and DEF CON in Las Vegas, Aug 7-8.RSVP
Socket
Socket
Sign inDemoInstall

@shopware/api-gen

Package Overview
Dependencies
Maintainers
0
Versions
380
Alerts
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

@shopware/api-gen

Shopware CLI for API client generation.


Version published
Maintainers
0
Created

Readme

Source

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;
  };
};

[!IMPORTANT]
Overriding components or operations in the TS files requires you to have a full object definitions!

Partial overrides

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:

{
  "patches": "./api-types/storeApiTypes.overrides.json"
}

and then inside the storeApiTypes.overrides.json file you can add your patches:

{
  "components": {
    "Cart": [
      {
        "required": ["price"]
      },
      {
        "required": ["errors"]
      }
    ]
  }
}

you apply this as 2 independent patches, or combine it as a single patch without array:

{
  "components": {
    "Cart": {
      "required": ["price", "errors"]
    }
  }
}

Creating multiple patches is useful when you want to apply different changes to the same object, which can also be corrected on the backend side independently. This way specific patches are becoming outdated and you get the notification that you can remove them safely.

[!NOTE]
Check our current default patches to see more examples: source.

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"

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.

options:

pnpx @shopware/api-gen validateJson --help

# validate JSON file
pnpx @shopware/api-gen validateJson --apiType=store

this searches for api-types/storeApiTypes.json file and validates it. Use loadSchema command first to fetch your JSON file.

Prepare your config file named api-gen.config.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": "./api-types/storeApiTypes.overrides.json" // -> path to your overrides file, default is fetched from api-client repository
}

Changelog

Full changelog for stable version is available here

Latest changes: 1.0.3

Patch Changes

  • #1113 65212d1 Thanks @patzick! - Parse Json5 responses when using default overrides

  • #1112 2065d00 Thanks @patzick! - Fixed adding missing components in overrides. Used when component name is overriden and no component definition is provided for it.

  • #1103 c9a4965 Thanks @trimethylpentan! - Re-enabled generation for GenericRecords for openAPI objects

Keywords

FAQs

Package last updated on 16 Jul 2024

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc