Comment générer du code client à partir de votre spécification API dans Apidog

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 : bonne URL, en-têtes, jeton d’authentification, paramètres de requête, puis intégration dans un appel requests ou fetch. Une seule erreur de copie peut provoquer une réponse 401 difficile à diagnostiquer.

Essayez Apidog dès aujourd’hui

Vous n’avez pas besoin d’écrire ce code répétitif à la main. Si votre API est conçue dans Apidog, la plateforme lit la définition du point de terminaison et produit un extrait prêt à copier-coller dans votre stack : cURL, Python requests, JavaScript fetch, Axios, etc.

Ce guide montre comment :

1. Générer un appel client à partir d’un point de terminaison.
2. Inclure les valeurs réellement envoyées, y compris l’authentification.
3. Générer des corps POST et PUT.
4. Garder les extraits alignés sur votre spécification.
5. Vérifier le contrat avec Apidog CLI.

Pour comparer plusieurs approches, consultez aussi ce récapitulatif des outils de génération de code API.

L’idée repose sur une spécification comme source unique de vérité, le même principe que la spécification OpenAPI. Définissez correctement le contrat une fois, puis dérivez les appels clients depuis cette définition.

Ce que génère réellement Apidog

Apidog transforme une définition de point de terminaison en extrait de requête pour un langage et une bibliothèque HTTP donnés.

Par exemple, pour GET /orders, sélectionnez Python puis Requests. Le générateur produit un appel incluant :

• l’URL ;
• le chemin ;
• les paramètres de requête ;
• les en-têtes déclarés ;
• la syntaxe adaptée à la bibliothèque choisie.

Il s’agit d’un générateur de requêtes pour un point de terminaison, pas d’un générateur de SDK complet. Vous obtenez par exemple :

• une commande cURL ;
• un bloc Python requests;
• un extrait JavaScript fetch ou Axios.

Ne vous attendez pas à un paquet client versionné, typé, avec modèles, pagination et helpers intégrés.

Cette approche s’intègre naturellement dans un flux de développement d’API axé sur la conception : vous définissez le contrat, générez l’appel depuis ce contrat, puis tous les consommateurs utilisent la même référence.

Deux façons d’ouvrir le générateur

Apidog propose deux points d’entrée vers le même générateur.

Depuis la documentation

1. Ouvrez l’onglet Documentation de votre API.
2. Sélectionnez le point de terminaison.
3. Cliquez sur Générer le code client.

Utilisez cette méthode lorsque vous consultez déjà la documentation et souhaitez récupérer rapidement un appel.

Depuis l’onglet Exécuter

1. Ouvrez l’onglet Exécuter.
2. Construisez ou testez votre requête.
3. Cliquez sur l’icône de code </>.

Cette méthode est pratique lorsque vous êtes en train d’envoyer et de déboguer une requête.

Dans les deux cas, choisissez ensuite votre langage et votre variante HTTP pour obtenir l’extrait correspondant.

Générer un appel Python pour GET /orders

Prenons un point de terminaison réaliste :

GET /orders

Il retourne les commandes d’un client, avec filtrage par statut et pagination.

Étape 1 : choisir Python Requests

Depuis l’onglet Documentation, cliquez sur Générer le code client.

Apidog propose notamment les variantes suivantes :

• 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, C, C#, Objective-C, Ruby, OCaml, Dart, R et HTTP brute.

Choisissez Python puis Requests. À partir de la spécification, Apidog peut générer un appel de ce type :

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 cet extrait dans votre script, puis adaptez uniquement les valeurs qui doivent dépendre de votre environnement.

Étape 2 : comprendre les limites d’un extrait issu de la spécification

Un extrait généré depuis la spécification contient :

• la structure de l’appel ;
• les paramètres déclarés ;
• les exemples éventuellement définis ;
• les en-têtes documentés.

En revanche, il n’inclut pas automatiquement les valeurs réelles utilisées pendant une exécution, comme un véritable jeton :

Authorization: Bearer <token>

Pour une API protégée, vous devrez soit ajouter le jeton manuellement, soit générer le code depuis une requête réellement envoyée.

Étape 3 : générer le code avec les valeurs réellement envoyées

Pour capturer les paramètres et l’authentification effectivement utilisés :

1. Ouvrez l’onglet Exécuter.
2. Renseignez les paramètres de requête.
3. Ajoutez votre méthode d’authentification.
4. Cliquez sur Envoyer.
5. Ouvrez l’onglet Requête réelle.
6. Faites défiler jusqu’au code client généré.

En mode design-first, les paramètres sont préremplis depuis la spécification. En mode request-first, vous les ajoutez manuellement dans l’onglet Exécuter.

Après l’envoi, l’extrait peut inclure les valeurs concrètes utilisées :

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())

Ne commitez jamais un jeton réel dans Git. Traitez-le comme un secret, conformément aux recommandations de la documentation Stripe sur les clés.

Préférez une variable d’environnement :

import os
import requests

url = "https://api.example.com/orders"

headers = {
    "Accept": "application/json",
    "Authorization": f"Bearer {os.environ['API_TOKEN']}",
}

params = {
    "status": "shipped",
    "page": "1",
}

response = requests.get(url, headers=headers, params=params, timeout=30)
response.raise_for_status()

print(response.json())

Générer des corps de requête pour POST et PUT

Les appels GET n’ont généralement pas de corps. Pour un POST /orders ou un PUT /orders/{id}, construisez d’abord le corps dans l’onglet Exécuter, puis envoyez la requête avant de récupérer l’extrait dans Requête réelle.

Pour les corps JSON et XML, vous pouvez :

• sélectionner un exemple prédéfini dans la spécification ;
• utiliser Auto-générer pour créer une structure conforme au schéma.

Le menu Auto-générer propose deux modes :

• Exemples : choisissez un exemple de corps prédéfini ;
• Générer à chaque fois : régénérez des données à chaque utilisation selon les règles de mock et le schéma.

Utilisez les options de Préférence d’auto-génération selon votre besoin :

• 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 ;
• Utiliser l’exemple de requête.

Choisissez Utiliser d’abord les valeurs d’exemple si votre spécification contient des exemples fiables. Choisissez Utiliser la valeur de mock si vous avez besoin de données réalistes générées pour chaque champ.

Les options d’auto-génération des corps nécessitent Apidog 2.7.0 ou une version ultérieure. Si elles ne sont pas visibles, mettez l’application à jour.

Une spécification enrichie avec des schémas et des exemples facilite cette étape. Vous pouvez notamment améliorer cette base en générant automatiquement la documentation API à partir d’OpenAPI.

Pour les valeurs qui changent à chaque appel, comme un horodatage ou un identifiant aléatoire :

1. Cliquez sur l’icône de baguette magique près d’un champ.
2. Ou utilisez Insérer une valeur dynamique dans un corps JSON ou XML.
3. Envoyez la requête.
4. Récupérez le code final dans Requête réelle.

Extrait ponctuel ou code applicatif structuré ?

Choisissez le niveau de structure selon l’usage du code généré.

Utiliser un extrait de requête unique

Préférez cURL, fetch ou un simple requests.get() pour :

• déboguer une réponse 403 ;
• partager un appel reproductible dans un ticket ;
• vérifier rapidement un point de terminaison dans un terminal ;
• ajouter un exemple à une documentation.

Exemple cURL :

curl --request GET \
  --url 'https://api.example.com/orders?status=shipped&page=1' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $API_TOKEN"

Structurer l’appel dans votre application

Si l’appel est utilisé dans plusieurs parties de l’application, encapsulez l’extrait généré dans une fonction ou un module de service.

import os
import requests


class OrdersClient:
    def __init__(self, base_url: str):
        self.base_url = base_url
        self.session = requests.Session()
        self.session.headers.update(
            {
                "Accept": "application/json",
                "Authorization": f"Bearer {os.environ['API_TOKEN']}",
            }
        )

    def list_orders(self, status: str, page: int = 1) -> dict:
        response = self.session.get(
            f"{self.base_url}/orders",
            params={"status": status, "page": page},
            timeout=30,
        )
        response.raise_for_status()
        return response.json()

Centralisez les éléments partagés, notamment l’URL de base, les en-têtes et les variables d’environnement. Le guide sur la configuration des paramètres globaux dans Apidog explique comment définir ces valeurs une fois afin qu’elles soient réutilisées par les requêtes.

Garder le code généré précis avec une approche spec-first

Le code généré n’est fiable que si la spécification l’est.

Par exemple, si vous ajoutez le paramètre region à GET /orders, mais continuez d’utiliser un ancien extrait, celui-ci devient obsolète :

GET /orders?status=shipped&page=1&region=eu

Adoptez une règle simple :

1. Mettez à jour la spécification.
2. Testez le point de terminaison.
3. Régénérez l’extrait.
4. Remplacez le code copié dans votre projet si nécessaire.

Le mode spec-first d’Apidog aide à maintenir la définition comme source d’autorité. Les extraits générés reflètent ainsi le contrat actuel plutôt qu’une version périmée.

Pour comprendre ou ajuster les variantes JavaScript, la documentation MDN sur l’API Fetch reste une bonne référence.

Automatiser la vérification avec Apidog CLI

La génération d’extraits client est une action effectuée dans l’interface Apidog : il n’existe pas de commande CLI distincte qui émet directement du code client.

En revanche, Apidog CLI permet de vérifier les éléments dont dépend ce code :

• une spécification à jour ;
• des scénarios de test qui confirment le comportement réel de l’API.

Installez le CLI avec Node.js v16+ :

npm install -g apidog-cli

Authentifiez-vous :

apidog login --with-token <YOUR_ACCESS_TOKEN>

Exécutez ensuite un scénario de test enregistré :

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli

Paramètres :

• -t : ID du scénario de test ;
• -e : ID de l’environnement ;
• -r : rapporteur, par exemple cli, html ou junit.

Intégrez cette commande dans votre pipeline CI. Le guide sur les GitHub Actions avec Apidog CLI montre comment automatiser cette vérification à chaque push.

Le CLI ne génère pas le client, mais il protège le contrat sur lequel le client généré repose.

FAQ

Le code généré inclut-il ma clé API ou mon jeton ?

Non, pas par défaut. Un extrait généré uniquement depuis la spécification contient la structure et les exemples définis, mais pas forcément les valeurs réellement envoyées ou l’autorisation.

Pour inclure ces valeurs, envoyez d’abord la requête, puis récupérez le code depuis l’onglet Requête réelle. Ne partagez et ne commitez jamais un jeton réel.

Quels langages et bibliothèques sont disponibles ?

Apidog propose notamment :

• Shell : cURL, Httpie, wget, PowerShell ;
• JavaScript : Fetch, Axios, jQuery, XHR et autres ;
• Python : http.client, Requests ;
• Java : Unirest, OkHttp ;
• Go ;
• PHP ;
• Swift, C, C#, Ruby, Dart, R et autres.

Choisissez le langage et la variante dans le panneau du générateur.

Pourquoi les options d’auto-génération ne sont-elles pas visibles ?

Les options d’auto-génération pour les corps de requête nécessitent Apidog 2.7.0 ou une version ultérieure. Mettez l’application à jour, puis ouvrez l’onglet Exécuter pour un corps JSON ou XML.

La génération de code client est-elle une fonctionnalité payante ?

La documentation Apidog ne distingue pas explicitement une offre gratuite, payante, cloud ou auto-hébergée pour cette fonctionnalité. La seule condition de version mentionnée concerne l’auto-génération des corps de requête, disponible à partir de la version 2.7.0.

Vous pouvez télécharger Apidog et essayer le générateur.

Comment vérifier qu’un appel généré fonctionne réellement ?

Générez l’extrait, puis créez un test enregistré pour le point de terminaison concerné. Ce guide sur l’écriture d’un scénario de test avec Apidog explique comment procéder.

Exécutez ensuite ce scénario avec le CLI dans votre CI afin qu’un contrat rompu fasse échouer la build avant de régénérer ou distribuer un nouvel extrait client.

En résumé

La génération de code client dans Apidog transforme une spécification de point de terminaison en requête prête à être copiée dans votre langage. Pour obtenir les paramètres et l’authentification réellement utilisés, envoyez la requête puis récupérez le code dans l’onglet Requête réelle.

Gardez la spécification à jour, régénérez les extraits après chaque évolution du contrat et exécutez des tests enregistrés dans votre CI.

Téléchargez Apidog, définissez GET /orders, envoyez une requête de test, puis copiez un appel client fonctionnel en quelques clics.