Générer des clients et des interfaces serveur à partir d'un document OpenAPI, et les garder générés

Objectif

Dériver des bibliothèques clientes typées ainsi que des types de requêtes et de réponses côté serveur à partir du document OpenAPI, afin que le document reste le contrat unique et que le code écrit à la main ne puisse pas en diverger silencieusement.

Prérequis

Un document OpenAPI qui se valide, avec un operationId sur chaque opération : la spécification le définit comme une chaîne unique servant à identifier l'opération, que les outils peuvent utiliser pour identifier les opérations, et dont les générateurs dérivent les noms de méthodes. Un générateur dont le langage de sortie peut être lu et compris ; OpenAPI Generator recense des générateurs clients et serveurs par langage. Une décision sur l'emplacement du code généré : commité dans le dépôt, ou produit lors de la construction.

Étapes

1. Figer la version du générateur dans le dépôt (une étiquette d'image de conteneur ou un script d'encapsulation). La sortie générée change d'une version de générateur à l'autre, et un générateur non figé produit des différences parasites.
2. Générer dans un répertoire dédié ne contenant rien d'écrit à la main. Placer la commande exacte dans le lanceur de tâches afin que tout le monde, y compris la CI, régénère de la même manière.
3. Configurer plutôt que modifier : la documentation d'usage recense --additional-properties pour les options du générateur, --type-mappings pour les substitutions de types et --template-dir pour des modèles copiés lorsque la sortie a besoin de changements structurels. La documentation de personnalisation décrit .openapi-generator-ignore, calqué sur .gitignore, comme le moyen d'empêcher le générateur d'écraser les fichiers listés, tels qu'un README ou un wrapper maintenu à la main.
4. Côté serveur, ne générer que les interfaces et les modèles, les implémenter dans des fichiers séparés, et laisser le compilateur signaler chaque opération manquante ou dont la signature a changé.
5. Côté client, envelopper le client généré dans une fine couche écrite à la main qui ajoute les nouvelles tentatives, l'authentification et la journalisation, de sorte que la partie générée puisse être remplacée intégralement.
6. Ajouter une tâche de CI qui régénère et échoue sur git diff --exit-code lorsque la sortie est commitée ; lorsqu'elle ne l'est pas, faire dépendre la construction de l'étape de génération.
7. À chaque modification du document, régénérer, exécuter les tests, et lire le diff du code généré pendant la revue : il montre exactement quels consommateurs sont affectés.

Résultat attendu

Le document OpenAPI change en premier et le code suit mécaniquement ; un changement de contrat qui casserait un consommateur se manifeste par une erreur de compilation ou un diff de code généré, plutôt qu'à l'exécution.

Limites et base de vérification

Les générateurs couvrent le sous-ensemble courant de la spécification ; des schémas oneOf complexes, des callbacks et des schémas de sécurité inhabituels peuvent produire un code maladroit ou erroné, et la liste des problèmes connus du générateur fait alors partie de la dépendance. Le code généré est verbeux ; ce volume est le prix du contrat. La procédure est une synthèse de la documentation citée, non une comparaison mesurée.