Vous avez besoin d'une fausse API pour le développement. Le backend n'est pas prêt, ou le service tiers est limité en débit, ou vous voulez simplement que vos tests s'exécutent sans atteindre un serveur en production. La réponse habituelle est une API simulée (mock). La question est de savoir comment en mettre une en place.
Vous pouvez utiliser une interface graphique pour définir des routes et des réponses préenregistrées. C'est bien une fois. Mais une API simulée que vous construisez manuellement dans une application de bureau est difficile à reproduire, difficile à versionner et impossible pour l'intégration continue (CI) ou un agent de codage IA de recréer par lui-même. Une API simulée que vous définissez depuis la ligne de commande est différente. C'est une commande dans un script, une étape dans un pipeline, une ligne qu'un agent peut exécuter. Ce que vous tapez, une machine peut le taper aussi.
Ce guide couvre deux approches. Premièrement, la voie générale open-source : les serveurs d'API simulée (mock servers) à binaire unique que vous exécutez directement à partir d'un fichier, de sorte qu'une spécification ou un fichier JSON devient un point d'accès en direct en une seule commande. Ensuite, l'approche via l'interface en ligne de commande (CLI) Apidog, qui fonctionne différemment et mérite d'être comprise en soi. Si vous souhaitez d'abord un aperçu des options, notre sélection des meilleurs outils de simulation d'API et le guide des outils de simulation d'API REST vous donnent tous deux une vue d'ensemble plus large.
L'approche générale : exécuter un serveur d'API simulée à partir d'un fichier
Le mock CLI classique est un petit binaire que vous pointez vers un fichier. Donnez-lui une spécification ou un fichier de données, et il sert un véritable point d'accès HTTP sur un port local. Pas de projet, pas de connexion, pas de compte. Ces outils font une seule chose : transformer un fichier en une fausse API que vous pouvez appeler. Trois d'entre eux couvrent presque tous les cas.
Prism : servir une spécification OpenAPI
Si vous avez déjà un fichier OpenAPI, Prism de Stoplight est la simulation la moins exigeante à exécuter. Il lit vos paths, exemples et schémas, puis sert des réponses qui correspondent au contrat.
npx @stoplight/prism-cli mock ./openapi.yaml
Cela démarre un serveur sur http://127.0.0.1:4010 avec chaque opération de votre spécification connectée. Prism renvoie l'exemple que vous avez défini pour une réponse, ou en génère un valide et aléatoire à partir du schéma si vous l'avez omis. Il valide également les requêtes entrantes par rapport à la spécification, de sorte qu'un appel malformé obtient un 422 approprié au lieu d'une exécution silencieuse. Appelez-le pour vérifier qu'il est actif :
curl http://127.0.0.1:4010/orders/123
Prism est sans état, donc une requête POST ne persiste rien. C'est l'objectif lorsque vous voulez que la simulation reste fidèle au contrat. Pour une installation globale, exécutez npm install -g @stoplight/prism-cli et omettez le npx.
Mockoon CLI : exécuter un fichier de données en mode "headless"
Mockoon CLI exécute une simulation à partir d'un fichier de données, soit un fichier exporté depuis l'application de bureau gratuite Mockoon, soit une spécification OpenAPI simple. L'application de bureau vous permet de construire des routes visuellement ; la CLI exécute ce même environnement en mode "headless" dans l'intégration continue (CI) ou sur un serveur.
npx @mockoon/cli start --data ./env.json
Pointez --data vers un fichier d'environnement Mockoon ou un fichier OpenAPI JSON/YAML et il servira immédiatement, par défaut sur le port 3000. Ajoutez --port pour le modifier. Si le fichier de données provient d'une ancienne version de Mockoon, la CLI le migre en mémoire sans toucher à l'original. Installez-le globalement avec npm install -g @mockoon/cli pour avoir une commande mockoon-cli persistante. C'est une bonne option lorsque vous voulez des routes plus riches et affinées manuellement que celles qu'une simple spécification vous donne, tout en voulant les exécuter sans interface graphique. Un serveur de simulation léger pour une API RESTful se situe souvent ici.
json-server : simuler une API REST à partir de JSON
Lorsque vous n'avez pas encore de spécification, json-server est la voie la plus rapide. Vous écrivez un simple fichier JSON décrivant vos données, et il construit une API REST complète autour de celles-ci.
npx json-server db.json
Avec un fichier db.json contenant un tableau posts, cela sert http://localhost:3000/posts avec de véritables opérations GET, POST, PUT, PATCH et DELETE. Une requête POST ajoute réellement un enregistrement et le réécrit dans le fichier, vous obtenez donc gratuitement un comportement avec état, ce que Prism ne vous offrira pas. Vous obtenez également le filtrage, le tri et la pagination via les paramètres de requête. Installez-le globalement avec npm install -g json-server si vous voulez qu'il soit toujours dans votre PATH.
Voilà pour l'approche open source. Chaque outil est un binaire unique, s'exécute à partir d'un seul fichier et n'a besoin de rien d'autre. L'inconvénient est que chacun est une île à part. La simulation est séparée de votre conception réelle, de vos tests et de votre documentation, et vous devez maintenir les fichiers et les processus en cours d'exécution synchronisés vous-même. Si vous avez besoin d'une correspondance de requête exacte ou de la relecture, MockServer et WireMock vont plus loin, au prix d'un environnement d'exécution Java.
L'approche Apidog CLI : importer la spécification, scripter les attentes
Apidog simule différemment, et bien comprendre cela vous évitera toute confusion. L'interface en ligne de commande (CLI) apidog ne démarre pas de serveur de simulation local à partir d'un fichier. Il n'y a pas de commande apidog mock ./openapi.yaml. Au lieu de cela, Apidog héberge la simulation pour vous, et la CLI est la manière de lui fournir une spécification et de scripter des réponses personnalisées.
Une note honnête d'abord. Apidog n'est pas open source ; c'est un produit commercial avec un niveau gratuit. Ce que ce niveau gratuit, plus la CLI, vous offre, c'est un projet intégré, de sorte que la simulation, la conception et les tests partagent une seule source de vérité au lieu de trois fichiers et trois processus distincts. Si une simulation jetable à partir d'un seul fichier est tout ce dont vous avez besoin, un outil plus léger est préférable. Si votre simulation doit rester synchronisée avec votre API réelle à mesure qu'elle évolue, continuez à lire.
Installez et authentifiez-vous d'abord (le guide d'installation de l'Apidog CLI couvre la configuration du jeton) :
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Importer une spécification pour obtenir des simulations intelligentes hébergées
La première étape consiste à intégrer votre API dans un projet. Importez un fichier OpenAPI, et Apidog génère automatiquement une URL de simulation pour chaque point d'accès.
apidog import --project <PROJECT_ID> --format openapi --file ./openapi.json
C'est là qu'Apidog diffère de Prism et json-server. Vous n'exécutez pas de serveur ; l'importation vous donne une simulation intelligente hébergée pour chaque opération. La simulation intelligente lit les types et noms de champs de votre schéma, de sorte qu'un champ email renvoie un e-mail plausible et qu'un champ createdAt renvoie un horodatage d'apparence réelle, et non une chaîne aléatoire. apidog import accepte également les formats Swagger 2.0, Postman et Apidog, de sorte qu'une définition existante devient des simulations en direct en une seule commande.
Scripter des réponses personnalisées avec apidog mock
Les simulations auto-générées couvrent le cas courant. Lorsque vous avez besoin d'une réponse spécifique pour une requête spécifique, par exemple un 200 pour un identifiant utilisateur et un 404 pour un autre, vous ajoutez une "attente" de simulation (mock expectation). C'est ce que gère le groupe de commandes apidog mock, et il s'agit d'opérations CRUD sur ces attentes, et non d'un serveur que vous démarrez.
apidog mock --help
apidog mock list --project <PROJECT_ID>
apidog mock list --project <PROJECT_ID> --http-api-id <ENDPOINT_ID>
L'affichage renvoie du JSON structuré, vous pouvez donc le passer via jq pour trouver l'ID d'une attente et l'alimenter à la commande suivante. Pour en lire, modifier ou supprimer une :
apidog mock get --project <PROJECT_ID>
apidog mock update --project <PROJECT_ID> --file ./mock.json
apidog mock delete --project <PROJECT_ID>
Les sous-commandes create et update prennent un argument --file décrivant l'attente. Assurez-vous d'avoir la bonne structure avant de l'écrire, ce qui est expliqué ensuite.
Valider le fichier d'attente avant de l'écrire
Ne devinez pas le JSON. La CLI fournit un schéma pour chaque écriture, vous récupérez donc la structure, la remplissez et la validez avant l'écriture réelle. Une attente mal formée échoue rapidement au lieu d'être traitée silencieusement.
apidog cli-schema get mock-create
apidog cli-schema validate mock-create --file ./mock.json
apidog mock create --project <PROJECT_ID> --file ./mock.json
Récupérez le schéma, écrivez votre mock.json pour qu'il corresponde, validez-le, puis créez l'attente. Si la validation renvoie une sortie non nulle, le pipeline s'arrête avant qu'un fichier incorrect n'atteigne votre projet. Exécutez les mêmes trois étapes pour les mises à jour avec la clé de schéma mock-update. Chaque commande renvoie du JSON avec un bloc agentHints.nextSteps qui vous indique, ou à un agent, quoi exécuter ensuite, ce qui rend ce flux utilisable par les outils de codage IA et pas seulement par les humains. Le guide complet de l'Apidog CLI décrit le reste des groupes de commandes.
L'intégrer à l'intégration continue (CI)
Les deux approches s'intègrent à un pipeline car chaque commande a un code de sortie et une sortie texte. Une simulation basée sur un serveur et un test d'intégration dans le même job pourraient ressembler à ceci :
# start Prism in the background, then run tests against it
npx @stoplight/prism-cli mock ./openapi.yaml &
PRISM_PID=$!
npm test
kill $PRISM_PID
Le flux Apidog est différent dans sa forme : il n'y a pas de processus local à démarrer et à arrêter, car la simulation est hébergée. Vous validez et appliquez les attentes comme étape de configuration, et vos tests appellent directement l'URL de la simulation hébergée.
# ensure the expectation is well-formed, then apply it
apidog cli-schema validate mock-create --file ./mock.json
apidog mock create --project <PROJECT_ID> --file ./mock.json
Dans les deux cas, personne ne clique sur un bouton. C'est la raison principale de simuler depuis la ligne de commande (CLI) : une équipe axée sur les spécifications, un job d'intégration continue (CI) et un agent IA peuvent tous mettre en place la même fausse API à partir des mêmes commandes.
Difficultés courantes
S'attendre à ce que apidog mock démarre un serveur. Cela ne se produira pas. Il n'y a pas de apidog mock start, apidog mock serve, ou apidog mock ./file.yaml. Vous apidog import une spécification pour obtenir des simulations hébergées, et apidog mock gère les attentes personnalisées en plus de celles-ci. Si vous voulez un processus local que vous lancez à partir d'un fichier, il s'agit de Prism, Mockoon CLI ou json-server.
Ignorer l'étape de schéma lors d'une écriture. Les commandes apidog mock create et update prennent un argument --file, et une forme incorrecte échoue ou écrit quelque chose que vous ne vouliez pas. Exécutez toujours cli-schema get et cli-schema validate en premier. Ce sont deux commandes supplémentaires qui vous évitent une session de débogage.
Prism semble vide car votre spécification est mince. La simulation de Prism n'est aussi bonne que vos exemples. Si une réponse n'a pas d'exemple et un schéma vague, vous obtenez des données vagues. Ajoutez des exemples à la spécification et la simulation sera plus précise.
Attentes avec état d'un outil sans état. Les simulations de contrat de Prism et Apidog ne persistent pas les écritures. Si vous avez besoin d'un POST puis d'un GET pour renvoyer le nouvel enregistrement, utilisez json-server ou une attente Apidog qui renvoie la forme souhaitée.
En résumé
La simulation depuis la ligne de commande (CLI) transforme une tâche fastidieuse en commandes que vous pouvez scripter, réviser et confier à l'intégration continue (CI) ou à un agent. L'approche open source vous offre des serveurs à binaire unique que vous exécutez à partir d'un fichier : Prism pour une spécification OpenAPI, Mockoon CLI pour un fichier de données en mode "headless", json-server pour une API REST instantanée à partir de JSON. L'approche Apidog fonctionne différemment ; vous importez une spécification une seule fois pour obtenir des simulations intelligentes hébergées, puis vous scriptez des réponses personnalisées avec apidog mock et la protection de validation cli-schema.
Choisissez en fonction de ce que vous avez déjà et de l'endroit où la simulation doit résider. Si vous voulez un serveur jetable à partir d'un seul fichier, les outils open source sont parfaits. Si vous voulez que la simulation reste synchronisée avec votre conception et vos tests dans un seul projet, téléchargez Apidog, installez la CLI et mettez en place vos simulations sans toucher à la souris.