OpenAPI Generator est un outil open-source qui transforme une spécification OpenAPI ou Swagger en code fonctionnel : SDK clients, stubs de serveur et fichiers de configuration. Vous installez son CLI, le pointez vers votre spécification, choisissez un générateur comme typescript-axios ou spring, et il écrit le code dans un dossier de sortie. Ce guide vous montre comment l'installer, lister les générateurs disponibles et produire des clients et des serveurs pour plusieurs langages.
Qu'est-ce qu'OpenAPI Generator
OpenAPI Generator lit une description d'API lisible par machine et en émet le code source. Donnez-lui un fichier openapi.yaml (ou JSON) et il peut générer une bibliothèque cliente pour appeler cette API, un stub de serveur qui l'implémente, ainsi que de la documentation et des fichiers de configuration.
Il prend en charge OpenAPI v2 (l'ancien format Swagger) et OpenAPI v3. Le projet est maintenu par l'organisation OpenAPITools sur GitHub, avec des modèles pour des dizaines de langages et de frameworks.
La distinction clé : il s'agit d'un générateur de code, et non d'un générateur de documentation. Les outils de documentation comme Swagger UI ou Redoc rendent votre spécification en pages HTML lisibles par l'homme. OpenAPI Generator produit plutôt du code que vous compilez et déployez. Il peut également émettre de la documentation Markdown, mais son rôle principal est de générer des SDK et des stubs.
Comment il se rapporte à Swagger Codegen
Si vous avez déjà utilisé Swagger Codegen, OpenAPI Generator vous semblera familier. Il a été créé à partir de Swagger Codegen en mai 2018, entre les versions 2.3.1 et 2.4.0 de Swagger Codegen, par plus de 40 de ses principaux contributeurs et créateurs de modèles.
Le fork est survenu après un désaccord sur l'orientation de Swagger Codegen 3.0.0. La communauté souhaitait un cycle de publication plus rapide et plus ouvert. Les notes officielles du fork décrivent le projet comme étant basé sur Swagger Codegen 2.4.0-SNAPSHOT, de sorte que les deux partagent des racines profondes. Si vous hésitez entre les deux, la comparaison des alternatives à Swagger Codegen couvre les différences pratiques.
Installation d'OpenAPI Generator
Vous avez quatre chemins d'installation courants. Choisissez celui qui correspond à votre stack.
npm (le plus courant)
Le wrapper npm est le point d'entrée le plus simple pour la plupart des équipes. Il télécharge et gère le JAR sous-jacent pour vous.
npm install @openapitools/openapi-generator-cli -g
Vous pouvez également l'exécuter sans installation globale :
npx @openapitools/openapi-generator-cli version
Homebrew (macOS)
brew install openapi-generator
JAR autonome
OpenAPI Generator est une application Java, vous pouvez donc télécharger directement le JAR depuis Maven Central et l'exécuter avec Java. Cela évite entièrement la couche npm ou Homebrew.
wget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/7.23.0/openapi-generator-cli-7.23.0.jar -O openapi-generator-cli.jar
java -jar openapi-generator-cli.jar help
Vérifiez Maven Central pour le dernier numéro de version avant de télécharger.
Docker
L'image officielle vous permet de générer du code sans rien installer localement. Montez votre répertoire de travail dans le conteneur afin qu'il puisse lire votre spécification et écrire la sortie.
docker pull openapitools/openapi-generator-cli
docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \
-i /local/openapi.yaml -g go -o /local/out/go
Lister les générateurs disponibles
Avant de générer quoi que ce soit, voyez quels générateurs existent. Chaque générateur cible un langage et un framework, comme java, python ou spring.
openapi-generator-cli list
Pour un affichage compact, une ligne par générateur, utilisez l'option courte et divisez par des virgules :
openapi-generator-cli list -s | tr ',' '\n'
La liste sépare les générateurs de clients (pour appeler une API) des générateurs de serveurs (pour en implémenter une), ainsi que les générateurs de documentation et de schémas.
Génération d'un SDK client
La commande principale est generate. Elle prend trois arguments que vous utiliserez à chaque fois :
-i, --input-specpointe vers votre fichier de spécification ou URL.-g, --generator-namesélectionne le générateur à exécuter.-o, --outputdéfinit le répertoire de sortie.
Voici un client TypeScript basé sur Axios :
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client
Cela écrit un client typé dans ./client. Chaque opération de votre spécification devient une méthode, et chaque schéma devient un modèle.
Le même modèle fonctionne pour différents langages. Échangez le nom du générateur et le dossier de sortie :
openapi-generator-cli generate -i openapi.yaml -g java -o ./client-java
openapi-generator-cli generate -i openapi.yaml -g python -o ./client-python
openapi-generator-cli generate -i openapi.yaml -g go -o ./client-go
Parce que le code provient d'une seule spécification, chaque client reste cohérent avec le contrat. Lorsque la spécification change, vous régénérez et vos SDK suivent.
Génération de stubs de serveur
Les générateurs de serveurs inversent la direction. Au lieu de code qui appelle votre API, vous obtenez une structure qui l'implémente, avec le routage, les modèles de requête et les interfaces de gestionnaire câblés. Vous remplissez la logique métier.
Voici un stub de serveur Spring Boot :
openapi-generator-cli generate -i openapi.yaml -g spring -o ./server-spring
Le projet généré vous fournit des contrôleurs et des DTO correspondant à votre spécification. Vous implémentez les méthodes d'interface, et les formes de requête et de réponse sont déjà définies pour vous. Cela maintient le serveur en cours d'exécution aligné avec le contrat publié.
Configuration de la sortie
La sortie par défaut est rarement exactement ce que vous voulez. OpenAPI Generator vous offre plusieurs contrôles.
Propriétés supplémentaires
La plupart des générateurs exposent des options par langage via --additional-properties (alias court -p). Passez-les sous forme de paires clé=valeur séparées par des virgules :
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client \
--additional-properties=npmName=@acme/api-client,supportsES6=true,withSeparateModelsAndApi=true
Chaque générateur documente ses propres propriétés, alors consultez la page du générateur pour la liste complète des clés qu'il accepte.
Un fichier de configuration
Lorsque la ligne de commande devient longue, déplacez les options dans un fichier de configuration. JSON et YAML sont tous deux pris en charge.
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client -c config.yaml
Un fichier de configuration conserve vos paramètres de génération sous contrôle de version à côté de la spécification, ce qui rend les builds reproductibles.
Ignorer des fichiers
OpenAPI Generator lit un fichier .openapi-generator-ignore dans le répertoire de sortie. Il utilise la même syntaxe que .gitignore. Utilisez-le pour empêcher le générateur d'écraser les fichiers que vous avez édités manuellement.
# .openapi-generator-ignore
*.md
src/custom/**
Vous pouvez pointer vers un fichier d'ignorance à un autre emplacement avec --ignore-file-override <emplacement>.
Modèles personnalisés
Chaque générateur est piloté par des modèles Mustache. Si la sortie par défaut ne correspond pas à votre style, copiez les modèles, modifiez-les et passez votre répertoire avec -t :
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client \
-t ./my-templates
C'est l'outil idéal lorsque vous avez besoin d'un en-tête personnalisé, d'un client HTTP différent ou de conventions de nommage internes intégrées à chaque fichier généré.
Exécution en CI
La génération de code fait partie de votre pipeline, et non du poste de travail d'un seul développeur. Régénérez le client à chaque modification de spécification afin que le SDK validé ne s'écarte jamais du contrat. Voici une étape GitHub Actions utilisant npx :
- name: Generate API client
run: npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client
Vous pouvez faire échouer la build si la sortie régénérée diffère de ce qui est commité, ce qui permet de détecter les spécifications et les SDK qui sont désynchronisés.
Gardez la spécification comme votre source unique de vérité
OpenAPI Generator n'est aussi bon que la spécification que vous lui fournissez. On ne tire rien de bon de ce qui est mauvais : une spécification vague ou invalide produit un SDK vague ou cassé. L'étape la plus précieuse se produit donc avant même d'exécuter generate. Vous rendez la spécification correcte, complète et stable.
C'est là qu'Apidog intervient. Apidog est une plateforme API tout-en-un native d'OpenAPI, de sorte que votre travail de conception et votre spécification sont le même artefact. Vous concevez ou importez l'API, et Apidog conserve le document OpenAPI comme source de vérité à partir de laquelle tout le reste découle.
Un flux de travail propre ressemble à ceci :
- Concevez ou importez la spécification OpenAPI dans Apidog. Le support des branches vous permet de travailler sur les modifications de manière isolée, de manière similaire au contrôle de version d'OpenAPI avec Git.
- Validez et linter la spécification avant de générer. Une spécification qui passe un linter OpenAPI et un validateur Swagger produit un code plus propre avec moins de surprises.
- Exportez la spécification validée, puis fournissez-la à OpenAPI Generator pour vos SDK et stubs.
Vous pouvez également maintenir la spécification synchronisée avec votre dépôt, par exemple en synchronisant la spécification OpenAPI avec GitHub, et examiner les modifications avec un diff OpenAPI avant leur déploiement. Si vous abandonnez des outils plus anciens, la comparaison des alternatives à Swagger pour la conception et les tests d'API est un bon point de départ.
Là où Apidog s'arrête et OpenAPI Generator commence
Il est utile d'être précis ici. Apidog ne génère pas de SDK clients complets ni de stubs de serveur. C'est le travail d'OpenAPI Generator, et les deux sont complémentaires plutôt que concurrents.
Apidog vous fournit des extraits de requêtes clients prêts à être copiés pour chaque endpoint, dans de nombreux langages et clients HTTP. Ce sont des exemples par requête que vous pouvez coller dans un script, et non un SDK packagé. Pour une bibliothèque générée et versionnée ou un squelette de serveur, vous exécutez OpenAPI Generator sur la spécification produite par Apidog.
Apidog propose également son propre exécuteur de tests en ligne de commande, l'Apidog CLI, qui est distinct de la génération de code. Il exécute vos tests d'API en CI ; il ne génère pas de SDK. Installez-le et utilisez-le comme ceci :
npm install -g apidog-cli@latest
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t <testScenarioId> \
-e <envId> \
-r cli,html \
-n 1
Vous passez l'authentification avec --access-token, -t sélectionne le scénario de test, -e choisit l'environnement à utiliser, et -r sélectionne les reporters. Exécutez-le sur une version LTS actuelle de Node.js. Pour les détails de configuration, consultez le guide d'installation de l'Apidog CLI et le tutoriel sur le test d'une API REST depuis la ligne de commande.
Ainsi, le cycle complet est le suivant : concevoir et valider la spécification dans Apidog, générer les SDK et les stubs avec OpenAPI Generator, puis vérifier l'API en cours d'exécution avec l'Apidog CLI.
Essayez Apidog gratuitement, aucune carte de crédit requise.
Questions Fréquemment Posées
Qu'est-ce qu'OpenAPI Generator ?
OpenAPI Generator est un outil open-source de l'organisation OpenAPITools qui génère du code à partir d'une spécification OpenAPI ou Swagger. Il produit des SDK clients, des stubs de serveur, de la documentation et des fichiers de configuration, et prend en charge OpenAPI v2 et v3.
Comment utiliser OpenAPI Generator ?
Installez l'outil en ligne de commande (par exemple npm install @openapitools/openapi-generator-cli -g), puis exécutez generate avec trois options : -i pour votre spécification, -g pour le générateur, et -o pour le dossier de sortie. Exécutez d'abord openapi-generator-cli list pour voir tous les générateurs disponibles.
Comment fonctionne OpenAPI Generator ?
Il analyse votre spécification en un modèle interne, puis rend ce modèle via des modèles Mustache pour la cible choisie. Chaque opération devient une méthode ou un gestionnaire, et chaque schéma devient un modèle typé. Vous pouvez surcharger les modèles avec -t pour modifier la sortie.
Comment générer un SDK client à partir d'une spécification OpenAPI ?
Choisissez un générateur de client et exécutez generate. Par exemple, openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client construit un client TypeScript typé. Remplacez typescript-axios par java, python ou go pour cibler d'autres langages.
Comment générer des stubs de serveur ?
Choisissez un générateur de serveur. Pour un squelette Spring Boot, exécutez openapi-generator-cli generate -i openapi.yaml -g spring -o ./server-spring. La sortie inclut des contrôleurs et des modèles de requête de votre spécification, et vous implémentez la logique du gestionnaire.
Quelle est la différence entre OpenAPI Generator et Swagger Codegen ?
OpenAPI Generator a été créé à partir de Swagger Codegen en mai 2018 par plus de 40 de ses contributeurs, qui souhaitaient un cycle de publication plus rapide et piloté par la communauté. Les deux partagent une base commune, mais OpenAPI Generator a maintenant sa propre feuille de route, son ensemble de générateurs et son calendrier de publication.
Comment générer un SDK PHP à partir d'une spécification OpenAPI ?
Utilisez le générateur php : openapi-generator-cli generate -i openapi.yaml -g php -o ./client-php. Exécutez openapi-generator-cli list pour confirmer le nom exact du générateur et pour voir d'autres options de framework PHP avant de générer.