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
QUERYouitemSchema, 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.0produit un document que tous les outils lisent. -
Ce qu'elle coûte : une traduction
vers un format moins expressif. Les types multiples
deviennent
nullableouanyOf, une listeexamplesdevient un seulexample. 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.
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.
- L'ancien générateur, relancé avec le lockfile commité, redonne l'ancien code à l'octet.
-
Avec le nouveau, les fronts compilent et les tests du
client passent, sur un
fetchsimulé. L'outil a changé, pas le contrat. - 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.
- OpenAPI Initiative, publication de la 3.2.0 (19 septembre 2025), spécification 3.2.0 et styles de paramètres.
-
API Platform,
OpenAPI
(export,
--spec-version=3.0.0), versions 4.4.0 et 5.0.0 du 17 septembre 2026, CHANGELOG (OpenAPI 3.2.0, #8350). - API Platform, code de la 5.0.2 : OpenApiFactory, LegacyOpenApiNormalizer, DeserializeProvider, DefaultPropertyMetadataFactory, SchemaPropertyMetadataFactory et PropertySchemaChoiceRestriction.
- openapi-typescript, passage en maintenance (19 septembre 2026), options de la CLI et middlewares d'openapi-fetch.
-
Redocly,
detectSpecde @redocly/openapi-core 1.34.14 et 1.34.15, dates des versions. - hey-api, notes de la 0.99.0, configuration du parser et ticket #2660.
-
hey-api, code de la 0.99.0 :
choix de l'analyseur,
parser.patch,transforms.enums, CLI et client fetch. -
TypeScript,
satisfies; moon, héritage des tâches, options de tâche et moon run ; GitHub, commandes de workflow. - Lychen, pull request 238 et pull request 243 : une mise en œuvre open source du contournement, puis de la bascule vers hey-api, dans un monorepo moon.
- Lychen, pull request 258 et pull request 263 : la configuration partagée, la génération depuis une URL, le client commun et la tâche de dérive.