Le problème

Le service order de notre boutique expose son API avec API Platform. Le front Vue l'appelle à travers un SDK TypeScript, généré depuis la spécification OpenAPI exportée et commitée dans le monorepo. Fil rouge : la liste des commandes filtrée par statut (status[]) et la modification d'une commande (PATCH, en JSON Merge Patch).

API Platform 4.4 et 5.0, publiées le 17 septembre 2026, exportent en OpenAPI 3.2.0, version parue le 19 septembre 2025. Il n'existe pas d'export en 3.1 : la seule autre cible documentée est la 3.0.0.

Un SDK généré par openapi-typescript 7.13, et appelé avec openapi-fetch, bute sur la nouvelle spec : Unsupported OpenAPI version: 3.2.0. Le 19 septembre 2026, le mainteneur d'openapi-typescript annonce la fin des mises à jour, sans successeur recommandé.

Le message vient de @redocly/openapi-core, qu'openapi-typescript utilise pour lire le document. Jusqu'à sa 1.34.14, il ne reconnaît que 3.0 et 3.1 ; la 1.34.15 (25 mai 2026) lit un 3.2 comme un 3.1. Le même openapi-typescript refuse ou accepte donc la spec selon le lockfile.

Trois réflexes se présentent : changer le numéro de version de la spec, forcer l'export en 3.0, retoucher le code généré. Chacun cache le problème au lieu de le traiter.

Les options

Rebaptiser la spec en 3.1

  • Ce qu'elle règle : une ligne avant le générateur (jq '.openapi = "3.1.0"'). Si la spec n'utilise aucun ajout de 3.2, la sortie ne change pas.
  • Ce qu'elle coûte : la spec ment sur sa version. Le jour où l'API utilise la méthode QUERY ou itemSchema, le générateur l'ignore sans erreur. Et l'outil reste sans maintenance.

Exporter en 3.0 depuis API Platform

  • Ce qu'elle règle : bin/console api:openapi:export --spec-version=3.0.0 produit un document que tous les outils lisent.
  • Ce qu'elle coûte : une traduction vers un format moins expressif. Les types multiples deviennent nullable ou anyOf, une liste examples devient un seul example. Le SDK décrit alors un document que l'API ne sert pas par défaut.

Changer de générateur

  • Ce qu'elle règle : @hey-api/openapi-ts lit tout document à partir de 3.1.0 avec son analyseur 3.1, et la spec 3.2 passe. Sa version stable, la 0.99.0, date du 22 juin 2026.
  • Ce qu'elle coûte : une version 0.x, qui peut casser d'une mineure à l'autre (la 0.99.0 annonce quatre changements cassants). openapi-fetch ne se pose pas dessus : chaque appel change de forme. Les ajouts de 3.2 restent à faire (ticket #2660).

Écrire le client à la main

  • Ce qu'elle règle : plus de générateur du tout. C'est notre choix pour les contrats de messages, tant qu'ils restent peu nombreux.
  • Ce qu'elle coûte : le compilateur ne vérifie plus le contrat d'une API REST entière. Chaque évolution se recopie, et un oubli ne se voit qu'à l'exécution.

Notre recommandation

Le générateur est une dépendance remplaçable. Une seule configuration l'épingle, la génération est reproductible, une tâche de CI détecte la dérive et une preuve accompagne la bascule. Les écarts de la spec se corrigent dans une étape de patch documentée, jamais dans le code généré.

Nous choisissons donc @hey-api/openapi-ts et gardons la spec en 3.2. La rebaptiser repousserait le changement d'outil ; l'exporter en 3.0 ferait décrire au SDK un document traduit.

Un générateur épinglé et remplaçable : la CI vérifie que le SDK découle de la spec API order , API Platform 5.0 bin/console api:openapi:export ou une URL --input Spec 3.2.0 commitée openapi.json 2 Étape de patch documentée deepObject vers form , garde-fou 3.2 SDK commité, jamais édité generated/order-api/ 1 Front Vue client configuré par createApiClient Tâche de dérive en CI 1 SDK régénéré depuis la spec commitée un écart : échec, bloquant 2 spec réexportée depuis l'API un écart : avertissement seulement Générateur épinglé, config partagée @hey-api/openapi-ts 0.99.0 Bascule entre deux générateurs ancien : openapi-typescript 7.13 relancé avec le lockfile : mêmes octets nouveau : @hey-api/openapi-ts les fronts compilent, les tests passent mêmes specs commitées : le contrat ne bouge pas Jamais : retoucher generated/ à la main, ni rebaptiser une spec 3.2 en 3.1 sans garde-fou

Une configuration partagée, un générateur épinglé

Chaque SDK ne déclare que le nom de son API et sa spec. Les plugins, le patch et le dossier de sortie vivent dans un package commun, seul endroit où le générateur est déclaré. Sa version y est exacte, car une 0.x ne promet rien d'une mineure à l'autre.

Monter de version devient une pull request délibérée, qui régénère tous les SDK. Le lockfile fait partie de la configuration : l'épisode d'openapi-core montre qu'une dépendance transitive suffit à changer le résultat.

Une génération reproductible

La même configuration génère depuis la spec commitée, la référence, ou depuis une URL : openapi-ts --input <url> ne remplace que l'entrée. L'URL sert à essayer une API de recette ; la revue porte sur un SDK généré depuis un fichier commité.

Une étape de patch, pas de retouche

Certains écarts de la spec gênent le générateur : un style que la norme ne définit pas, un ajout qu'il ne lit pas. Nous les traitons dans parser.patch, avant toute analyse, chaque règle avec sa raison. Le dossier generated/ n'est jamais modifié à la main : la génération suivante effacerait la retouche.

Une tâche de dérive en CI

Le premier contrôle régénère le SDK depuis la spec commitée et exige un generated/ inchangé. Il bloque : un écart trahit une retouche, ou un générateur monté sans régénération. Le second réexporte la spec depuis l'API et avertit sans bloquer, car l'API peut évoluer avant que le front n'adopte le nouveau contrat.

Une preuve de bascule

Changer de générateur réécrit tout le code généré : relire ce diff ne prouve rien. Comme pour tout refactoring, la preuve porte sur l'entrée, les specs commitées.

  1. L'ancien générateur, relancé avec le lockfile commité, redonne l'ancien code à l'octet.
  2. Avec le nouveau, les fronts compilent et les tests du client passent, sur un fetch simulé. L'outil a changé, pas le contrat.
  3. L'adoption de l'export 3.2 de l'API suit dans une pull request séparée. Avant la bascule, une génération depuis un export 3.2 réel, non commité, vérifie que les fronts compilent.

Les compromis assumés

Un générateur en 0.x. Sa sortie peut changer à chaque mineure : nous ne le montons qu'en régénérant tout.

Du code généré commité. Les diffs sont longs. La tâche de dérive garantit qu'ils découlent de la spec : la revue porte sur la spec et la configuration.

Des énumérations écrites deux fois. Les objets as const du front répètent des valeurs de la spec, mais satisfies les tient au type généré.

Une spec 3.2 lue comme une 3.1. Un garde-fou dans le patch fait échouer la génération si la spec contient un ajout de 3.2.

Le signal qui doit faire réexaminer ce choix : un patch qui grossit, ou une montée de hey-api qui change tout le SDK. Le premier appelle des corrections côté API, le second une nouvelle comparaison des générateurs.

Mise en œuvre

Les exemples utilisent API Platform 5.0, @hey-api/openapi-ts 0.99.0, Vue 3.5 et moon 2. Côté API, la tâche order:export-openapi lance bin/console api:openapi:export --output=openapi.json.

1. La configuration commune

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

// Ajouts d'OpenAPI 3.2 que l'analyseur 3.1 de hey-api ne lit pas (hey-api#2660).
const UNREAD_3_2 = /"(itemSchema|additionalOperations)"|"in":"querystring"/;

/** api : en kebab-case. input : la spec commitée (relative à la lib du SDK) ou une 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} : la spec utilise un ajout d'OpenAPI 3.2 que le générateur ignore.`,
            );
          }
        },
        // API Platform documente des filtres de liste (status[]) en deepObject, style
        // qu'OpenAPI réserve aux objets. L'API lit status[]=a&status[]=b : c'est du 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'],
  });
}

Le package.json de ce package déclare "@hey-api/openapi-ts": "0.99.0", sans ^. Un SDK se réduit à ceci :

// 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. Les tâches de génération

Les SDK (tag api-sdk) héritent des mêmes tâches :

# .moon/tasks/api-sdk.yml
inheritedBy:
  tags: ['api-sdk']
tasks:
  generate-api:
    command: openapi-ts # depuis la spec commitée
    options:
      cache: false # la tâche réécrit 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. Le client et ses intercepteurs

Un package commun configure le client de chaque 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',
};

/** Rend à une écriture sans corps le Content-Type que le client généré a retiré. */
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 : l'URL et le statut ; cause : le corps lu. Une erreur réseau passe telle quelle. */
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) {
    // Facultatif : sans jeton, la requête part sans 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;
}

Le front crée orderApiClient avec createApiClient(createClient, { baseUrl, bearerToken: getAccessToken }), que ses composables d'endpoint passent au SDK. Chaque opération devient une fonction nommée d'après son operationId, fixé côté API. api.PATCH('/orders/{id}', { params: { path: { id } }, body }) devient updateOrder({ client: orderApiClient, path: { id }, body }).

4. Les pièges de la bascule

Une propriété avec default n'est plus requise. API Platform publie la valeur par défaut d'une propriété PHP comme default, sans l'ajouter à required. DeliveryMode vient des contrats partagés (app-contracts).

// src/ApiResource/OrderResource.php (service order), extrait
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;

    // Dans le schéma : "enum" en ligne et "default", sans "required".
    #[Assert\Choice(choices: [DeliveryMode::STANDARD, DeliveryMode::EXPRESS])]
    public string $deliveryMode = DeliveryMode::STANDARD;
}

openapi-typescript rendait obligatoire toute propriété dotée d'un default (option --default-non-nullable, active par défaut). hey-api suit required : deliveryMode devient facultatif, et le code qui supposait sa présence ne compile plus. À raison : il doit gérer l'absence.

Des énumérations en ligne. Assert\Choice place la liste dans le schéma de la propriété, pas dans un composant. Or hey-api ne sait émettre un objet à l'exécution que pour les énumérations en composants. Plutôt que de les promouvoir (parser.transforms.enums) sous des noms choisis par le générateur, nous écrivons l'objet à côté de generated/ :

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

// Une valeur ajoutée ou retirée par l'API casse la compilation à la régénération suivante.
export type DeliveryMode = NonNullable<OrderJsonld['deliveryMode']>;
export const DeliveryMode = {
  standard: 'standard',
  express: 'express',
} as const satisfies { [K in DeliveryMode]: K };

deepObject sur un tableau. API Platform 5.0 peut documenter un filtre de liste (status[]) en style: deepObject, que la norme réserve aux objets. Pour un tableau, le client de hey-api n'accepte que form, spaceDelimited ou pipeDelimited : le SDK ne compile pas. Le patch rétablit form, et la requête part en status[]=placed&status[]=paid.

D'autres filtres ont leurs écarts de documentation, comme ComparisonFilter.

Le Content-Type d'une écriture sans corps. Le client généré retire cet en-tête quand l'appel n'a pas de corps. API Platform répond alors 415 à toute opération qu'il doit désérialiser. jsonLdContentType le remet, pour les seules écritures.

Des intercepteurs, pas des middlewares. openapi-fetch appelle ses onResponse dans l'ordre inverse de leur enregistrement, hey-api ses intercepteurs dans l'ordre. Une réponse en erreur arrive à l'intercepteur error avec son corps déjà lu.

5. La tâche de dérive

# .github/workflows/order-api-sdk.yml (extrait)
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 et yarn install --immutable, comme le workflow principal.
      - name: SDK commité = produit de la spec commitée (bloquant)
        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: Spec commitée = export de l'API (avertissement)
        run: |
          moon run order:export-openapi
          git diff --quiet -- services/order/openapi.json || echo "::warning::Spec order modifiée : SDK à régénérer."

git status --porcelain liste aussi les fichiers non suivis : un fichier généré en plus fait échouer le contrôle. yarn.lock figure dans les chemins, car une dépendance du générateur peut changer sa sortie.

Checklist

  • Le générateur déclaré dans un seul package, à la version exacte, lockfile commité.
  • Chaque SDK réduit au nom de son API et à sa spec.
  • Les écarts de la spec corrigés dans parser.patch, avec un garde-fou contre les ajouts de 3.2.
  • generated/ jamais modifié ; les énumérations à côté.
  • En CI : SDK régénéré identique (bloquant), spec réexportée comparée (avertissement).
  • Pour une bascule : l'ancien générateur redonne l'ancien code à l'octet, le nouveau compile et passe les tests.

Sources

Versions relevées le 15 novembre 2026 : API Platform 5.0.7 et 4.4.8, @hey-api/openapi-ts 0.99.0 (dernière stable), openapi-typescript 7.13.0, moon 2.6.5.