The problem

Our shop's order service exposes its API with API Platform. The Vue front calls it through a TypeScript SDK, generated from the OpenAPI specification that is exported and committed to the monorepo. Running example: the order list filtered by status (status[]) and the update of an order (PATCH, in JSON Merge Patch).

API Platform 4.4 and 5.0, released on 17 September 2026, export OpenAPI 3.2.0, a version published on 19 September 2025. There is no 3.1 export: the only other documented target is 3.0.0.

An SDK generated by openapi-typescript 7.13, and called with openapi-fetch, trips over the new spec: Unsupported OpenAPI version: 3.2.0. On 19 September 2026, the maintainer of openapi-typescript announced the end of updates, with no recommended successor.

The message comes from @redocly/openapi-core, which openapi-typescript uses to read the document. Up to its 1.34.14, it only recognises 3.0 and 3.1; 1.34.15 (25 May 2026) reads a 3.2 as a 3.1. The same openapi-typescript therefore rejects or accepts the spec depending on the lockfile.

Three reflexes come up: change the spec's version number, force the 3.0 export, patch the generated code by hand. Each one hides the problem instead of dealing with it.

The options

Relabel the spec as 3.1

  • What it solves: one line before the generator (jq '.openapi = "3.1.0"'). If the spec uses no 3.2 addition, the output does not change.
  • What it costs: the spec lies about its version. The day the API uses the QUERY method or itemSchema, the generator ignores it without an error. And the tool stays unmaintained.

Export 3.0 from API Platform

  • What it solves: bin/console api:openapi:export --spec-version=3.0.0 produces a document every tool reads.
  • What it costs: a translation into a less expressive format. Multiple types become nullable or anyOf, a list of examples becomes a single example. The SDK then describes a document the API does not serve by default.

Change generators

  • What it solves: @hey-api/openapi-ts reads any document from 3.1.0 up with its 3.1 parser, and the 3.2 spec goes through. Its stable version, 0.99.0, dates from 22 June 2026.
  • What it costs: a 0.x version, which may break from one minor to the next (0.99.0 lists four breaking changes). openapi-fetch does not sit on top of it: every call changes shape. The 3.2 additions are still to come (issue #2660).

Write the client by hand

  • What it solves: no generator at all. It is our choice for message contracts, as long as they stay few.
  • What it costs: the compiler no longer checks the contract of a whole REST API. Every change is copied by hand, and an omission only shows at runtime.

Our recommendation

The generator is a replaceable dependency. A single configuration pins it, the generation is reproducible, a CI task detects drift and a proof comes with the switch. Gaps in the spec are fixed in a documented patch step, never in the generated code.

So we pick @hey-api/openapi-ts and keep the spec at 3.2. Relabelling it would only postpone the change of tool; exporting 3.0 would make the SDK describe a translated document.

A pinned, replaceable generator: the CI checks that the SDK derives from the spec order API, API Platform 5.0 bin/console api:openapi:export or a URL --input Committed 3.2.0 spec openapi.json 2 Documented patch step deepObject to form , 3.2 guard Committed SDK, never edited generated/order-api/ 1 Vue front client set up by createApiClient Drift task in CI 1 SDK regenerated from the committed spec any difference: failure, blocking 2 spec re-exported from the API any difference: a warning only Pinned generator, shared config @hey-api/openapi-ts 0.99.0 Switch between two generators old: openapi-typescript 7.13 run again with the lockfile: same bytes new: @hey-api/openapi-ts the fronts compile, the tests pass same committed specs: the contract does not move Never: edit generated/ by hand, or relabel a 3.2 spec as 3.1 without a guard

A shared configuration, a pinned generator

Each SDK only declares its API's name and its spec. The plugins, the patch and the output folder live in a shared package, the only place where the generator is declared. Its version is exact there, because a 0.x promises nothing from one minor to the next.

Upgrading becomes a deliberate pull request, which regenerates every SDK. The lockfile is part of the configuration: the openapi-core episode shows that a transitive dependency is enough to change the result.

A reproducible generation

The same configuration generates from the committed spec, the reference, or from a URL: openapi-ts --input <url> only replaces the input. The URL is for trying out a staging API; the review covers an SDK generated from a committed file.

A patch step, not hand edits

Some gaps in the spec get in the generator's way: a style the standard does not define, an addition it does not read. We handle them in parser.patch, before any parsing, each rule with its reason. The generated/ folder is never edited by hand: the next generation would wipe out the edit.

A drift task in CI

The first check regenerates the SDK from the committed spec and requires an unchanged generated/. It blocks: a difference betrays a hand edit, or a generator upgraded without regeneration. The second re-exports the spec from the API and warns without blocking, because the API may change before the front adopts the new contract.

A proof for the switch

Changing generators rewrites all the generated code: reviewing that diff proves nothing. As for any refactoring, the proof is about the input, the committed specs.

  1. The old generator, run again with the committed lockfile, gives back the old code byte for byte.
  2. With the new one, the fronts compile and the client's tests pass, on a stubbed fetch. The tool changed, not the contract.
  3. Adopting the API's 3.2 export follows in a separate pull request. Before the switch, a generation from a real 3.2 export, not committed, checks that the fronts compile.

The trade-offs we accept

A 0.x generator. Its output may change with each minor: we only upgrade it by regenerating everything.

Committed generated code. The diffs are long. The drift task guarantees they derive from the spec: the review covers the spec and the configuration.

Enums written twice. The front's as const objects repeat values from the spec, but satisfies holds them to the generated type.

A 3.2 spec read as a 3.1. A guard in the patch fails the generation if the spec contains a 3.2 addition.

The signal that should make us revisit this choice: a patch that keeps growing, or a hey-api upgrade that changes the whole SDK. The first calls for fixes on the API side, the second for a new comparison of generators.

Implementation

The examples use API Platform 5.0, @hey-api/openapi-ts 0.99.0, Vue 3.5 and moon 2. On the API side, the order:export-openapi task runs bin/console api:openapi:export --output=openapi.json.

1. The shared configuration

// libs/typescript/api-sdk-config/defineApiSdkConfig.ts
import { defineConfig } from '@hey-api/openapi-ts';

// OpenAPI 3.2 additions that hey-api's 3.1 parser does not read (hey-api#2660).
const UNREAD_3_2 = /"(itemSchema|additionalOperations)"|"in":"querystring"/;

/** api: in kebab-case. input: the committed spec (relative to the SDK library) or a URL. */
export function defineApiSdkConfig({ api, input }: { api: string; input: string }) {
  return defineConfig({
    input,
    output: `generated/${api}-api`,
    parser: {
      patch: {
        input: (spec) => {
          const pathItems = Object.values(spec.paths ?? {});
          if (
            UNREAD_3_2.test(JSON.stringify(spec)) ||
            pathItems.some((item) => item && 'query' in item)
          ) {
            throw new Error(`${api}: the spec uses an OpenAPI 3.2 addition the generator ignores.`);
          }
        },
        // API Platform documents list filters (status[]) as deepObject, a style
        // OpenAPI keeps for objects. The API reads status[]=a&status[]=b: that is form.
        operations: (_method, _path, operation) => {
          const parameters = (operation.parameters ?? []) as {
            style?: string;
            schema?: { type?: unknown };
          }[];
          for (const parameter of parameters) {
            if (parameter.style === 'deepObject' && parameter.schema?.type === 'array') {
              parameter.style = 'form';
            }
          }
        },
      },
    },
    plugins: ['@hey-api/typescript', '@hey-api/sdk', '@hey-api/client-fetch'],
  });
}

This package's package.json declares "@hey-api/openapi-ts": "0.99.0", without ^. An SDK comes down to this:

// libs/typescript/order-api-sdk/openapi-ts.config.ts
import { defineApiSdkConfig } from '@app/api-sdk-config';

export default defineApiSdkConfig({
  api: 'order',
  input: '../../../services/order/openapi.json',
});

2. The generation tasks

The SDKs (tag api-sdk) inherit the same tasks:

# .moon/tasks/api-sdk.yml
inheritedBy:
  tags: ['api-sdk']
tasks:
  generate-api:
    command: openapi-ts # from the committed spec
    options:
      cache: false # the task rewrites generated/
  generate-api-from-url:
    # moon run order-api-sdk:generate-api-from-url -- https://staging.example.com/docs.jsonopenapi
    command: openapi-ts --input
    options:
      cache: false
      runInCI: false

3. The client and its interceptors

A shared package sets up the client of every API:

// libs/typescript/api-client/createApiClient.ts
type RequestInterceptor = (request: Request) => Request | Promise<Request>;
type ErrorInterceptor = (error: unknown, response: Response | undefined) => unknown;
type ApiClient = {
  interceptors: {
    request: { use(fn: RequestInterceptor): unknown };
    error: { use(fn: ErrorInterceptor): unknown };
  };
};

const WRITE_TYPES: Partial<Record<string, string>> = {
  POST: 'application/ld+json',
  PUT: 'application/ld+json',
  PATCH: 'application/merge-patch+json',
};

/** Gives a write without a body the Content-Type the generated client removed. */
export const jsonLdContentType: RequestInterceptor = (request) => {
  const type = WRITE_TYPES[request.method];
  if (type && !request.headers.has('Content-Type')) request.headers.set('Content-Type', type);
  return request;
};

/** Message: the URL and the status; cause: the parsed body. A network error goes through as is. */
export const httpStatusError: ErrorInterceptor = (error, response) =>
  response
    ? new Error(`${response.url}: ${response.status} ${response.statusText}`, { cause: error })
    : error;

export function createApiClient<
  Config extends { baseUrl?: string; throwOnError?: boolean },
  Client extends ApiClient,
>(
  createClient: (config?: Config) => Client,
  {
    baseUrl,
    bearerToken,
  }: { baseUrl: string; bearerToken?: () => string | undefined | Promise<string | undefined> },
): Client {
  const client = createClient({ baseUrl, throwOnError: true } as Config);
  if (bearerToken) {
    // Optional: without a token, the request goes out without Authorization.
    client.interceptors.request.use(async (request) => {
      const token = await bearerToken();
      if (token) request.headers.set('Authorization', `Bearer ${token}`);
      return request;
    });
  }
  client.interceptors.request.use(jsonLdContentType);
  client.interceptors.error.use(httpStatusError);
  return client;
}

The front creates orderApiClient with createApiClient(createClient, { baseUrl, bearerToken: getAccessToken }), which its endpoint composables pass to the SDK. Each operation becomes a function named after its operationId, set on the API side. api.PATCH('/orders/{id}', { params: { path: { id } }, body }) becomes updateOrder({ client: orderApiClient, path: { id }, body }).

4. The pitfalls of the switch

A property with a default is no longer required. API Platform publishes the default value of a PHP property as default, without adding it to required. DeliveryMode comes from the shared contracts (app-contracts).

// src/ApiResource/OrderResource.php (order service), excerpt
use ApiPlatform\Doctrine\Orm\State\Options;
use ApiPlatform\Metadata\ApiResource;
use App\Entity\Order;
use AppContracts\Order\DeliveryMode;
use Symfony\Component\Uid\Uuid;
use Symfony\Component\Validator\Constraints as Assert;

#[ApiResource(shortName: 'Order', stateOptions: new Options(entityClass: Order::class))]
final class OrderResource
{
    public Uuid $id;

    // In the schema: an inline "enum" and a "default", without "required".
    #[Assert\Choice(choices: [DeliveryMode::STANDARD, DeliveryMode::EXPRESS])]
    public string $deliveryMode = DeliveryMode::STANDARD;
}

openapi-typescript made every property with a default required (the --default-non-nullable option, on by default). hey-api follows required: deliveryMode becomes optional, and the code that assumed it was there no longer compiles. Rightly so: it must handle the absence.

Inline enums. Assert\Choice puts the list in the property's schema, not in a component. Yet hey-api can only emit a runtime object for enums declared as components. Rather than promote them (parser.transforms.enums) under names the generator picks, we write the object next to generated/:

// libs/typescript/order-api-sdk/enums.ts
import type { OrderJsonld } from './generated/order-api';

// A value the API adds or removes breaks the compilation at the next regeneration.
export type DeliveryMode = NonNullable<OrderJsonld['deliveryMode']>;
export const DeliveryMode = {
  standard: 'standard',
  express: 'express',
} as const satisfies { [K in DeliveryMode]: K };

deepObject on an array. API Platform 5.0 may document a list filter (status[]) with style: deepObject, which the standard keeps for objects. For an array, hey-api's client only accepts form, spaceDelimited or pipeDelimited: the SDK does not compile. The patch restores form, and the request goes out as status[]=placed&status[]=paid.

Other filters have their own documentation gaps, such as ComparisonFilter.

The Content-Type of a write without a body. The generated client removes this header when the call has no body. API Platform then answers 415 to any operation it has to deserialize. jsonLdContentType puts it back, for writes only.

Interceptors, not middleware. openapi-fetch calls its onResponse hooks in the reverse order of their registration, hey-api its interceptors in order. An error response reaches the error interceptor with its body already parsed.

5. The drift task

# .github/workflows/order-api-sdk.yml (excerpt)
on:
  pull_request:
    paths:
      - 'services/order/**'
      - 'libs/typescript/order-api-sdk/**'
      - 'libs/typescript/api-sdk-config/**'
      - '.moon/tasks/api-sdk.yml'
      - 'yarn.lock'
jobs:
  drift:
    runs-on: ubuntu-latest
    steps:
      # Checkout, proto, PHP and yarn install --immutable, as in the main workflow.
      - name: Committed SDK = output of the committed spec (blocking)
        run: |
          moon run order-api-sdk:generate-api
          changes=$(git status --porcelain -- libs/typescript/order-api-sdk/generated)
          [ -z "$changes" ] || { echo "$changes"; exit 1; }
      - name: Committed spec = API export (warning)
        run: |
          moon run order:export-openapi
          git diff --quiet -- services/order/openapi.json || echo "::warning::order spec changed: regenerate the SDK."

git status --porcelain also lists untracked files: an extra generated file fails the check. yarn.lock is among the paths, because a dependency of the generator can change its output.

Checklist

  • The generator declared in a single package, at an exact version, lockfile committed.
  • Each SDK reduced to its API's name and its spec.
  • Gaps in the spec fixed in parser.patch, with a guard against 3.2 additions.
  • generated/ never edited; the enums next to it.
  • In CI: regenerated SDK identical (blocking), re-exported spec compared (warning).
  • For a switch: the old generator gives back the old code byte for byte, the new one compiles and passes the tests.

Sources

Versions checked on 15 November 2026: API Platform 5.0.7 and 4.4.8, @hey-api/openapi-ts 0.99.0 (latest stable), openapi-typescript 7.13.0, moon 2.6.5.