npm package: @heyframe/api-gen
Description: Shopware CLI for API client generation.
Author: Shopware
Latest version: 1.3.3

# heyframe/frontends - api-gen

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

After generating schemas, you can use them in fully typed [API Client](https://www.npmjs.com/package/@heyframe/api-client).

To take a deep dive into the topic visit the [🧑‍🎓 API Client Tutorial](https://api-client-tutorial-composable-frontends.pages.dev) first.

## Usage

<!-- automd:pm-install name="@heyframe/api-gen" dev -->

```sh
# ✨ Auto-detect
npx nypm install -D @heyframe/api-gen

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

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

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

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

# deno
deno install --dev @heyframe/api-gen
```

<!-- /automd -->

## Features

Generator will create a new directory `api-types` with TypeScript schemas inside. Depending on the `apiType` parameter it will create `frontApiTypes.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::

- `frontApiTypes.overrides.ts` for front API
- `adminApiTypes.overrides.ts` for admin API

Example of overrides file:

<!-- automd:file src="packages/api-gen/tests/snapshots-override/simpleOverride.example.ts" code -->

```ts [simpleOverride.example.ts]
import type { components as mainComponents } from "./frontApiTypes";

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

<!-- /automd -->

> [!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:

```json
{
  "$schema": "https://raw.githubusercontent.com/heyframe/frontends/main/packages/api-gen/api-gen.schema.json",
  "patches": ["frontApiTypes.overrides.json"]
}
```

or you could use multiple patches and add your own overrides on top:

```json
{
  "$schema": "https://raw.githubusercontent.com/heyframe/frontends/main/packages/api-gen/api-gen.schema.json",
  "patches": [
    "https://raw.githubusercontent.com/heyframe/frontends/refs/heads/main/packages/api-client/api-types/frontApiSchema.overrides.json",
    "./api-types/myOwnPatches.overrides.json"
  ]
}
```

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

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

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

```json
{
  "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](https://raw.githubusercontent.com/heyframe/frontends/main/packages/api-client/api-types/frontApiSchema.overrides.json).

## Commands

### add shortcut to your `package.json` scripts

```json
{
  "scripts": {
    "generate-types": "heyframe-api-gen generate --apiType=front"
  }
}
```

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:

```bash
pnpx @heyframe/api-gen generate --help

# generate schemas from front API
pnpx @heyframe/api-gen generate --apiType=front

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

flags:

- `--debug` - display debug logs and additional information which can be helpful in case of issues
- `--logPatches` - display patched logs, useful when you want to fix schema in original file

### `loadSchema`

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

options:

```bash
pnpx @heyframe/api-gen loadSchema --help

# load schema from front API
pnpx @heyframe/api-gen loadSchema --apiType=front

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

flags:

- `--debug` - display debug logs and additional information which can be helpful in case of issues
- `--logPatches` - display patched logs, useful when you want to fix schema in original file

Remember to add `.env` file in order to authenticate with Shopware instance.

```bash
OPENAPI_JSON_URL="https://your-shop-instance.heyframe.front"
## This one needed to fetch front API schema
OPENAPI_ACCESS_KEY="YOUR_STORE_API_ACCESS_KEY"
## These two needed to fetch admin API schema
HEYFRAME_ADMIN_USERNAME="my@username.com"
HEYFRAME_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:

```bash
pnpx @heyframe/api-gen validateJson --help

# validate JSON file
pnpx @heyframe/api-gen validateJson --apiType=front
```

this searches for `api-types/frontApiTypes.json` file and validates it. Use [loadSchema](#loadSchema) command first to fetch your JSON file.

Prepare your config file named **api-gen.config.json**:

```JSON
{
  "$schema": "https://raw.githubusercontent.com/heyframe/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": "frontApiTypes.overrides.json" // -> path to your overrides file in api-types folder, default is fetched from api-client repository
}
```

### Programmatic usage

Each command can also be used programmatically within your own scripts:

#### `generate`

```ts
import { generate } from "@heyframe/api-gen";

await generate({ 
  cwd: process.cwd(),
  filename: "frontApiTypes.ts",
  apiType: "front",
  debug: true,
  logPatches: true,
});
```

#### `loadSchema`

```ts
import { loadSchema } from "@heyframe/api-gen";

await loadSchema({
  cwd: process.cwd(),
  filename: "frontApiTypes.json",
  apiType: "front",
});
```

#### `validateJson`

```ts
import { validateJson } from "@heyframe/api-gen";

await validateJson({
  cwd: process.cwd(),
  filename: "frontApiTypes.json",
  apiType: "front",
  logPatches: true,
  debug: true,
});
```

> [!NOTE]  
> Make sure that the required environment variables are set for the node process when executing commands programmatically.

## Links

- [🧑‍🎓 Tutorial](https://api-client-tutorial-composable-frontends.pages.dev)

- [📘 Documentation](https://frontends.heyframe.com)

- [👥 Community Slack](https://heyframecommunity.slack.com) (`#composable-frontends` channel)

<!-- AUTO GENERATED CHANGELOG -->

## Changelog

Full changelog for stable version is available [here](https://github.com/heyframe/frontends/blob/main/packages/api-gen/CHANGELOG.md)

### Latest changes: 1.3.3

### Patch Changes

- [#1942](https://github.com/heyframe/frontends/pull/1942) [`a344abb`](https://github.com/heyframe/frontends/commit/a344abba579c91c4f775e7be27ed882ca420fdc2) Thanks [@patzick](https://github.com/patzick)! - Allow shared parameters to be available in schema resolver.