ADR 0036 – OpenAPI écrit depuis TypeBox, types du client par openapi-typescript
Statut : Décidée. Date : 30/09/2026. Applique l’ADR 0009 (une seule définition sert de type, de validation et de documentation OpenAPI).
Contexte
Section intitulée « Contexte »packages/api-client doit être un « client typé généré depuis OpenAPI » (CLAUDE.md, découpage), mais aucun document OpenAPI n’existe et le paquet est vide. Les contrats de l’API sont déjà des schémas TypeBox dans packages/schemas, validés par Ajv. Il faut un document OpenAPI qui ne devienne pas une seconde source de vérité.
Décision
Section intitulée « Décision »- Les routes sont décrites une fois, dans un registre de
packages/schemas: méthode, chemin, paramètres, corps et réponses en TypeBox. Une fonction pure en tire le document OpenAPI 3.1, sans dépendance : TypeBox produit déjà du JSON Schema. - L’API le sert sur
GET /v1/openapi.json; le même document est versionné danspackages/api-client. openapi-typescript(licence MIT), en dépendance de développement depackages/api-clientseulement, génère les types du client depuis ce document. Rien n’est ajouté à l’exécution.- Un test de l’API échoue si une route Nest n’est pas au registre, ou l’inverse, ou si le document versionné est périmé.
Alternatives écartées
Section intitulée « Alternatives écartées »@nestjs/swagger: dépendance d’exécution, décorateurs sur chaque contrôleur et schémas TypeBox à rebrancher à la main. Deux descriptions de la même route à garder d’accord.- Client écrit à la main, sans OpenAPI : contredit le découpage, et chaque consommateur (back-office, terrain) recopierait les types.
openapi-fetchou un client entièrement généré : dépendance d’exécution de plus pour six routes ; de petites fonctions typées par les types générés suffisent.
Conséquences
Section intitulée « Conséquences »Une dépendance de développement et une étape generer dans packages/api-client, rejouée en intégration continue (le diff doit être vide). Toute nouvelle route passe par le registre : c’est le prix de la source unique. Le registre ne valide rien à lui seul : la validation reste celle d’Ajv (ADR 0009).
Stratégie de sortie
Section intitulée « Stratégie de sortie »Le document OpenAPI est un fichier standard, lu par n’importe quel générateur. Remplacer openapi-typescript ne change ni le registre, ni les routes, ni le document ; seul le script generer est à réécrire.