Vous avez un point de terminaison défini et vous souhaitez l'appeler depuis votre application. La partie fastidieuse consiste à traduire la spécification en code fonctionnel : la bonne URL, les en-têtes, le jeton d'authentification, la chaîne de requête, le tout intégré dans un appel requests ou un fetch. Copiez un seul caractère erroné et vous passerez vingt minutes à vous demander pourquoi le serveur renvoie une erreur 401.
Vous n'avez pas besoin d'écrire ce code récurrent à la main. Si votre API est conçue dans Apidog, la plateforme lit votre spécification de point de terminaison et vous fournit un extrait de requête prêt à être copié-collé dans le langage avec lequel vous travaillez : cURL pour une vérification rapide dans le terminal, Python requests pour un script, JavaScript fetch ou Axios pour un frontend. Ce guide vous expliquera comment générer ce code à partir d'un véritable point de terminaison, quand envoyer la requête en premier afin que l'extrait contienne des valeurs réelles, et comment maintenir la précision du code généré lorsque votre spécification change. Si vous souhaitez une vue d'ensemble plus large des options, notre récapitulatif des outils de génération de code API vous donne une perspective plus vaste ; ici, nous restons pratiques avec le générateur intégré.
L'idée repose sur le fait qu'une spécification est la source unique de vérité, le même principe derrière la spécification OpenAPI. Obtenez la bonne définition une fois, et le code de requête en découle.
Ce que fait réellement le générateur de code client
Apidog transforme une définition de point de terminaison en un extrait de requête par variante linguistique. Pointez-le vers GET /orders, choisissez Python et la bibliothèque Requests, et il écrira l'appel qui atteint ce chemin avec les en-têtes et les paramètres que votre spécification déclare. C'est un générateur de requêtes : il produit le code pour un seul appel, dans la syntaxe de votre langage et bibliothèque HTTP choisis.
Définissez correctement les attentes sur un point. Cette fonctionnalité génère le code de requête ou de client pour un point de terminaison, et non un SDK complet ou un paquet de bibliothèque client versionné. Si vous avez besoin d'une ligne curl, d'un bloc Python requests, ou d'un extrait JS fetch à insérer dans votre code, c'est ce que vous obtiendrez. La documentation ne décrit pas un générateur de bibliothèque complet, ne vous attendez donc pas à un SDK typé téléchargeable avec des modèles et des aides à la pagination intégrés.
Ceci s'associe naturellement à un flux de travail de développement d'API axé sur la conception. Vous définissez le contrat, générez le code de requête directement à partir de celui-ci, et chaque consommateur part de la même définition précise au lieu d'une capture d'écran collée dans Slack.
Deux façons d'ouvrir le générateur
Apidog vous offre deux points d'entrée vers la même fonctionnalité. Utilisez celui qui correspond à votre situation actuelle.
Le premier se trouve dans la documentation. Ouvrez l'onglet Documentation de votre API, puis cliquez sur le bouton Générer le code client sur le côté droit. C'est le chemin le plus rapide lorsque vous lisez la documentation d'un point de terminaison et que vous souhaitez obtenir son appel.
Le second se trouve dans le lanceur. Dans l'onglet Exécuter de l'API, cliquez sur l'icône de code </>. Celle-ci se trouve à côté de l'endroit où vous construisez et envoyez des requêtes, c'est donc le choix naturel lorsque vous testez déjà l'appel.
Les deux ouvrent le même panneau. De là, vous choisissez une langue et une variante, et Apidog écrit l'extrait.
Générer un appel client Python pour GET /orders
Voici le flux complet avec un point de terminaison réaliste : un appel GET /orders qui liste les commandes d'un client, filtrées par statut et paginées.
Étape 1 : Ouvrez le point de terminaison et choisissez votre langage
Ouvrez l'onglet Documentation pour le point de terminaison et cliquez sur Générer le code client. Dans le panneau, choisissez votre cible. Apidog prend en charge une longue liste de langages et de variantes, afin que vous puissiez correspondre exactement à votre stack :
- Shell: cURL, cURL-Windows, Httpie, wget, PowerShell
- JavaScript: Fetch, Axios, jQuery, XHR, Native, Request, Unirest
- Python: http.client, Requests
- Java: Unirest, OkHttp
- Go: Native
- PHP: cURL, Guzzle, pecl_http, HTTP_Request2
- Autres: Swift (URLSession), C (libcurl), C#, Objective-C, Ruby, OCaml, Dart, R, plus une option HTTP brute
Pour cet exemple, choisissez Python et la variante Requests. Apidog génère quelque chose comme ceci à partir de la spécification :
import requests
url = "https://api.example.com/orders"
querystring = {"status": "shipped", "page": "1"}
headers = {"Accept": "application/json"}
response = requests.get(url, headers=headers, params=querystring)
print(response.json())
Copiez-le, insérez-le dans votre script, et c'est un appel fonctionnel. C'est la voie "design-first" : l'extrait reflète exactement ce que votre point de terminaison déclare.
Étape 2 : Savoir ce qu'inclut l'extrait basé uniquement sur la spécification
Il y a une nuance à comprendre avant de coller. Le code généré directement à partir de la spécification API inclut uniquement la spécification API, et non les valeurs réelles des paramètres de requête ou votre jeton d'autorisation. Vous obtenez la forme de l'appel et toutes les valeurs d'exemple définies dans la spécification, mais pas l'en-tête Authorization: Bearer ... réel dont vous avez besoin pour atteindre un point de terminaison protégé.
C'est bien pour un appel sans authentification ou lorsque vous allez renseigner le jeton vous-même. Pour un GET /orders protégé, vous voulez les valeurs réelles dans le code.
Étape 3 : Envoyez la requête en premier pour capturer les valeurs réelles
Pour obtenir un extrait contenant les valeurs réelles des paramètres et les informations d'autorisation, envoyez d'abord la requête, puis lisez le code dans l'onglet Requête réelle.
Si vous travaillez en mode "design-first", c'est facile. Définissez le point de terminaison dans l'onglet Modifier, cliquez sur l'onglet Exécuter, et les paramètres de requête se rempliront automatiquement à partir de la spécification. Si vous préférez configurer les choses manuellement (mode "request-first"), saisissez les paramètres de requête manuellement dans l'onglet Exécuter. Dans tous les cas, ajoutez votre jeton d'authentification, puis cliquez sur Envoyer pour transmettre la requête.
Une fois la réponse reçue, passez à l'onglet Requête réelle et faites défiler vers le bas pour trouver le code client. Maintenant, l'extrait généré inclut les valeurs concrètes et l'en-tête d'authentification qui ont été réellement envoyés :
import requests
url = "https://api.example.com/orders"
querystring = {"status": "shipped", "page": "1"}
headers = {
"Accept": "application/json",
"Authorization": "Bearer sk_live_51H8xY2..."
}
response = requests.get(url, headers=headers, params=querystring)
print(response.json())
C'est la différence entre les deux approches. Le mode "design-first" remplit automatiquement les paramètres à partir de la spécification ; le mode "request-first" vous permet de les saisir. Les deux alimentent le même extrait de Requête réelle une fois que vous appuyez sur Envoyer. Traitez un vrai jeton comme celui ci-dessus comme un secret et ne l'incluez pas dans ce que vous commettez sur Git ; la même prudence que la documentation de Stripe recommande pour les clés de production s'applique ici.
Gestion des corps de requête pour POST et PUT
GET /orders n'a pas de corps, mais au moment où vous générez du code pour un POST /orders ou un PUT /orders/{id}, vous avez besoin d'un corps de requête dans l'extrait. Apidog vous aide à en construire un dans l'onglet Exécuter avant de générer.
Pour les corps JSON ou XML, vous avez deux sources. Utilisez un exemple prédéfini de la spécification du point de terminaison, ou cliquez sur Auto-générer pour créer une structure de corps qui correspond à votre schéma. Le menu déroulant Auto-générer vous offre deux modes :
- Exemples : sélectionnez manuellement un exemple de corps de requête prédéfini.
- Générer à chaque fois : régénérez les données à chaque utilisation, en suivant des règles de mock intelligentes afin d'obtenir à chaque fois des valeurs fraîches et valides selon le schéma.
Vous pouvez orienter la production des données via les sous-options de Préférence d'auto-génération : Utiliser d'abord les valeurs d'exemple, Utiliser d'abord les valeurs par défaut, Utiliser la valeur de mock, Générer uniquement les noms de champs et Utiliser l'exemple de requête. Choisissez Utiliser d'abord les valeurs d'exemple lorsque votre spécification contient de bons exemples et que vous souhaitez qu'ils soient respectés ; choisissez Utiliser la valeur de mock lorsque vous souhaitez des données générées réalistes pour chaque champ.
Une note de version : les options d'auto-génération pour les corps de requête nécessitent Apidog 2.7.0 ou ultérieur. Si vous ne les voyez pas, mettez à jour l'application. Un schéma bien spécifié avec des exemples, le genre que vous obtenez en générant automatiquement la documentation API à partir d'OpenAPI, permet à cette étape de produire des corps propres avec presque aucune édition manuelle.
Lorsque vous avez besoin d'une valeur qui change à chaque requête, comme un horodatage récent ou un ID de commande aléatoire, insérez une valeur dynamique plutôt que d'en coder une en dur. Cliquez sur l'icône de la baguette magique à côté d'une zone de saisie de paramètre, ou utilisez le bouton Insérer une valeur dynamique à l'intérieur d'un corps de requête JSON ou XML. Une fois le corps prêt, cliquez sur Envoyer, puis lisez l'extrait final dans l'onglet Requête réelle comme précédemment.
Quand utiliser un extrait de requête versus un appel de modèle métier
Un jugement rapide : quelle quantité de code devriez-vous copier ?
Optez pour un extrait de requête unique (cURL, fetch, un simple requests.get) lorsque vous effectuez une opération ponctuelle. Déboguer pourquoi un point de terminaison renvoie une erreur 403, partager un appel reproductible dans un ticket, effectuer une vérification rapide dans le terminal, ou coller un exemple dans votre propre documentation. C'est autonome et ne nécessite aucune structure environnante.
Orientez-vous vers le code plus complet, de style "modèle métier" (le bloc Axios ou requests avec les en-têtes, les paramètres et la gestion des réponses détaillés) lorsque l'appel réside dans une logique applicative réelle. Si GET /orders doit se trouver dans un module de service appelé depuis trois endroits, vous voulez la version structurée que vous pouvez encapsuler dans une fonction, ajouter la gestion des erreurs et réutiliser. Le générateur vous donne les deux formes selon la variante que vous choisissez ; faites correspondre la forme à l'endroit où le code va résider.
Si vous appelez les mêmes points de terminaison avec la même authentification sur l'ensemble d'un projet, il est souvent plus propre de centraliser les éléments partagés. Notre guide sur la configuration des paramètres globaux dans Apidog montre comment définir les en-têtes et les variables une seule fois afin que chaque appel généré les hérite au lieu de répéter le jeton dans chaque extrait.
Maintenir la précision du code généré avec l'habitude "spec-first"
Le code généré n'est correct que si la spécification qui le sous-tend l'est. Modifiez GET /orders pour ajouter un paramètre de requête region et oubliez de régénérer, et votre extrait copié sera silencieusement incorrect. La solution consiste à traiter la spécification comme l'élément que vous maintenez, et le code comme un résultat dérivé que vous régénérez à la demande. Le mode "spec-first" d'Apidog maintient la définition comme faisant autorité, de sorte que le code de requête que vous générez reflète toujours le contrat actuel, et non un contrat obsolète.
Pour la syntaxe des extraits eux-mêmes, la documentation MDN sur l'API Fetch est une référence solide lorsque vous souhaitez comprendre ou ajuster les variantes JavaScript produites par Apidog.
Automatisez le flux de travail avec l'Apidog CLI
La génération de code elle-même est une action d'interface graphique ; vous copiez un extrait depuis un panneau, et il n'y a pas de commande CLI distincte qui émet du code client. Ce que l'Apidog CLI fait bien, c'est de maintenir les deux éléments dont dépend cette génération : une spécification à jour et des tests réussis qui prouvent que le client généré fonctionne réellement.
Installez-le avec npm install -g apidog-cli (Node.js v16+) et authentifiez-vous :
apidog login --with-token <YOUR_ACCESS_TOKEN>
Importez les nouvelles modifications de la spécification afin que le code que vous générez reste à jour, et exécutez le scénario de test enregistré qui exerce le point de terminaison appelé par votre client :
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
Ici, -t est l'ID du scénario de test, -e est l'ID de l'environnement, et -r est le rapporteur (cli, html ou junit). Intégrez cela dans votre pipeline, comme le décrit notre guide sur les GitHub Actions Apidog CLI, et chaque push vérifiera que GET /orders se comporte toujours comme la spécification le promet avant que quiconque ne régénère un client à partir de celle-ci. Le CLI n'écrit pas votre code client, mais il protège le contrat sur lequel ce code est bâti.
FAQ
Le code généré inclut-il ma clé API et mon jeton ?
Non, pas par défaut. Le code généré à partir de la spécification API seule inclut uniquement la spécification, et non les valeurs réelles des paramètres ou l'autorisation. Pour obtenir un extrait avec votre jeton et vos valeurs réels, envoyez d'abord la requête, puis lisez le code dans l'onglet Requête réelle. Traitez tout jeton dans cet extrait comme un secret.
Quels langages et bibliothèques Apidog peut-il générer du code ?
Un large éventail. Shell (cURL, Httpie, wget, PowerShell), JavaScript (Fetch, Axios, jQuery, XHR, et plus), Python (http.client et Requests), Java (Unirest, OkHttp), Go, PHP, Swift, C, C#, Ruby, Dart, R, et autres. Vous choisissez le langage et la variante spécifique dans le panneau du générateur.
Pourquoi ne vois-je pas les options d'auto-génération pour les corps de requête ?
Ces options nécessitent Apidog 2.7.0 ou ultérieur. Mettez à jour l'application et elles apparaîtront dans l'onglet Exécuter lorsque vous construirez un corps JSON ou XML. Une fois disponibles, le menu déroulant Auto-générer propose Exemples et Générer à chaque fois, avec des sous-options de préférence pour la manière dont les valeurs sont produites.
La génération de code client est-elle une fonctionnalité payante ?
La documentation Apidog ne trace pas de ligne entre gratuit et payant ou entre cloud et auto-hébergé pour la génération de code client. La seule exigence de version mentionnée est que les options d'auto-génération des corps de requête nécessitent la version 2.7.0 ou ultérieure. Vous pouvez télécharger Apidog et essayer le générateur sans abonnement payant.
Comment m'assurer que l'appel généré fonctionne réellement ?
Générez l'extrait, puis vérifiez le point de terminaison avec un test enregistré. Notre tutoriel sur l'écriture d'un scénario de test avec Apidog montre comment en construire un, et le CLI peut l'exécuter en CI afin qu'un contrat rompu fasse échouer la build avant que vous ne régénériez un client à partir de celui-ci.
En résumé
La génération de code client dans Apidog transforme une spécification de point de terminaison en une requête prête à être copiée-collée dans le langage avec lequel vous travaillez, et l'onglet Requête réelle est l'astuce pour intégrer des valeurs réelles et l'authentification dans cet extrait au lieu d'un modèle vide. Maintenez la spécification comme faisant autorité, régénérez-la lorsqu'elle change, et laissez un test enregistré confirmer que l'appel fonctionne toujours. Téléchargez Apidog pour suivre, définissez votre point de terminaison GET /orders, et copiez un appel client fonctionnel en quelques clics.