DEV Community

Cover image for Comment un agent IA met à jour votre spec API avec la CLI Apidog
Antoine Laurent
Antoine Laurent

Posted on • Originally published at apidog.com

Comment un agent IA met à jour votre spec API avec la CLI Apidog

#ai #api #automation #cli

Modifier une spécification d’API à la main est une tâche précise et répétitive : renommer un champ, ajouter une valeur d’énumération ou rendre un paramètre obligatoire. Avec un agent IA, ces opérations peuvent être automatisées, à condition d’encadrer strictement les écritures pour éviter de casser les endpoints ou les schémas existants. La CLI Apidog fournit les garde-fous nécessaires : validation locale, branches IA isolées et fusion soumise à révision.

Essayez Apidog dès aujourd’hui

Ce guide complète l’approche qui permet à un agent de créer de la documentation API. Créer de nouvelles ressources est généralement additif et peu risqué. Modifier un contrat existant exige davantage de contrôles, car une mise à jour incomplète peut supprimer des données de votre spécification.

Ce que signifie « mettre à jour la spécification » via la CLI

Dans Apidog, une spécification regroupe les endpoints et les schémas de données d’un projet. Les opérations principales sont :

  • endpoint update : modifier un chemin, un paramètre ou une réponse ;
  • schema update : modifier un modèle de données référencé par des endpoints ;
  • import : importer un fichier OpenAPI complet et le concilier avec le projet.

Avant de déléguer ces commandes à un agent, retenez deux règles :

  1. Une mise à jour remplace l’objet envoyé, elle ne fusionne pas automatiquement les tableaux ou les propriétés.
  2. Les modifications doivent être réalisées dans une branche IA, puis relues avant fusion.

Le point critique : update remplace l’objet complet

Les commandes update ne fonctionnent pas comme un JSON Patch. Elles écrivent les champs fournis et ne fusionnent pas les éléments de tableau par ID.

Par exemple, envoyer un tableau parameters contenant un seul paramètre ne modifie pas ce paramètre : cela remplace tout le tableau et supprime les autres paramètres.

Utilisez toujours une boucle lecture → modification → validation → écriture :

# 1. Récupérer la ressource complète
apidog endpoint get <endpointId> --project <projectId>

# 2. Modifier localement l’objet complet
# Conserver les champs non concernés par le changement.

# 3. Valider la charge utile complète
apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file ./endpoint-full.json

# 4. Réécrire l’objet complet
apidog endpoint update <endpointId> --project <projectId> --file ./endpoint-full.json
Enter fullscreen mode Exit fullscreen mode

Ajoutez cette instruction explicitement au prompt ou aux règles de votre agent :

N’envoyez jamais d’objet partiel à update. Récupérez toujours la ressource complète, modifiez-la localement, validez-la, puis renvoyez-la intégralement.

Cette règle évite les suppressions silencieuses de champs, de paramètres ou de propriétés de schéma.

Travailler dans une branche IA

Évitez de donner immédiatement un accès direct à la branche principale. Une branche IA isole les changements de l’agent jusqu’à leur validation humaine, comme une pull request pour votre contrat d’API.

Étape 1 : créer la branche IA 

apidog branch create --project <projectId> --type ai \
  --from main --name "ai/20260713-from-main-refund-fields"
Enter fullscreen mode Exit fullscreen mode

Utilisez une convention de nommage lisible, par exemple :

ai/AAAAMMJJ-de-source-fonctionnalité
Enter fullscreen mode Exit fullscreen mode

La valeur de --from doit pointer vers votre branche principale ou une branche de sprint normale, pas vers une branche générale.

Une branche IA sans différence avec sa branche source est automatiquement archivée après 24 heures.

Étape 2 : importer les ressources existantes avec pick-to

Une branche IA démarre vide. Elle ne clone pas automatiquement les ressources de la branche source.

Avant de modifier un endpoint ou un schéma existant, importez-le dans la branche IA :

apidog branch pick-to --project <projectId> --type ai \
  --from main --to "ai/20260713-from-main-refund-fields" \
  --endpoint-ids <ids>
Enter fullscreen mode Exit fullscreen mode

Cette opération est requise uniquement pour les ressources existantes à modifier ou supprimer. Les ressources créées directement par l’agent dans la branche IA n’ont pas besoin d’être importées au préalable.

Étape 3 : appliquer la modification dans la branche

Ajoutez --branch à toutes les commandes de lecture et d’écriture :

apidog endpoint get <endpointId> --project <projectId> \
  --branch "ai/20260713-from-main-refund-fields"

apidog endpoint update <endpointId> --project <projectId> \
  --branch "ai/20260713-from-main-refund-fields" \
  --file ./endpoint-full.json
Enter fullscreen mode Exit fullscreen mode

La branche principale reste intacte. Si l’agent se trompe, l’impact est limité à une branche isolée et jetable.

Étape 4 : réviser puis fusionner

Une branche IA ne fusionne jamais automatiquement. Une fois le travail terminé, examinez les changements avant de les intégrer.

apidog merge-request --help

apidog branch merge --project <projectId> --type ai \
  --from "ai/20260713-from-main-refund-fields" \
  --to main \
  --endpoint-ids <ids>
Enter fullscreen mode Exit fullscreen mode

Si la branche cible est protégée, utilisez plutôt une demande de fusion via merge-request, puis approuvez-la dans le client Apidog.

La fusion directe avec branch merge nécessite des permissions de modification directe sur les branches source et cible.

Exemple : renommer un champ de schéma sans supprimer les autres

Supposons que vous deviez renommer amount en amountCents dans le schéma Refund, et convertir ce champ en entier.

Instruction à donner à l’agent :

Renomme le champ amount du schéma Refund en amountCents, transforme-le en entier, conserve tous les autres champs et valide l’objet avant écriture.

L’agent commence par récupérer le schéma complet depuis la branche IA :

apidog schema get <refundSchemaId> --project $PID \
  --branch "ai/20260713-from-main-refund-fields"
Enter fullscreen mode Exit fullscreen mode

Il modifie ensuite le jsonSchema complet :

{
  "name": "Refund",
  "jsonSchema": {
    "type": "object",
    "required": ["orderId", "amountCents"],
    "properties": {
      "orderId": { "type": "string" },
      "amountCents": { "type": "integer" },
      "reason": { "type": "string" }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Les propriétés orderId et reason sont conservées. L’agent ne doit pas envoyer uniquement la propriété amountCents, car update remplace l’objet fourni.

Enfin, il valide puis écrit la ressource :

# Valider la charge utile complète
apidog cli-schema validate schema-create --file ./refund-full.json

# Mettre à jour le schéma dans la branche IA
apidog schema update <refundSchemaId> --project $PID \
  --branch "ai/20260713-from-main-refund-fields" \
  --file ./refund-full.json
Enter fullscreen mode Exit fullscreen mode

Vous pouvez alors réviser le diff : un champ renommé, sans modification involontaire des autres propriétés.

Bloquer les changements cassants avant la fusion

Renommer un champ requis est un changement cassant. Les clients qui envoient encore amount échoueront désormais à la validation.

Ajoutez une règle de classification à votre agent :

Avant de fusionner un changement de spécification, classez-le :

- Non cassant :
  nouveau champ optionnel, nouveau point de terminaison, contrainte assouplie
  → résumer le changement et procéder à la demande de fusion.

- Cassant :
  champ renommé ou supprimé, nouveau champ requis, type renforcé
  → ARRÊTER.
  Signaler le changement cassant, les endpoints affectés et attendre une
  approbation humaine explicite.
Enter fullscreen mode Exit fullscreen mode

Grâce à la branche IA, ce point d’arrêt est réel : aucun changement ne touche la branche principale tant qu’une personne ne l’a pas approuvé.

Mettre à jour à partir d’un fichier OpenAPI

Si la modification existe déjà dans un fichier OpenAPI généré depuis le code, édité par une autre équipe ou produit par un autre outil, importez-le directement dans la branche IA :

apidog import --project <projectId> --format openapi --file ./openapi.json \
  --branch "ai/20260713-from-main-refund-fields"
Enter fullscreen mode Exit fullscreen mode

import accepte notamment OpenAPI 3.x, Swagger 2.0 et Postman.

Après révision et fusion, exportez la spécification pour vérifier le résultat :

apidog export --project <projectId> --format openapi \
  --oas-version 3.1 --output ./openapi.json
Enter fullscreen mode Exit fullscreen mode

Utilisez cette approche lorsque la source de vérité est externe à Apidog et doit être synchronisée. Préférez update lorsque Apidog est la source de vérité et que vous réalisez une modification ciblée.

Annuler le travail d’un agent

Si l’agent produit une modification incorrecte dans une branche IA, il suffit d’archiver la branche :

apidog branch archive "ai/20260713-from-main-refund-fields" \
  --project <projectId> --type ai
Enter fullscreen mode Exit fullscreen mode

La branche principale n’a pas été touchée, puisque le changement n’a jamais été fusionné.

C’est l’intérêt principal de l’isolation : une erreur devient une branche à archiver, plutôt qu’une modification à annuler manuellement sur la branche principale.

Gérer les permissions

Si une commande update ou import est bloquée, les permissions de modification IA externes du projet peuvent être désactivées.

Le flux recommandé reste le même :

  1. l’agent modifie une branche IA ;
  2. un humain révise les changements ;
  3. la fusion est approuvée explicitement.

Si vous souhaitez autoriser les modifications directes, le paramètre est disponible dans :

Paramètres du projet
→ Paramètres des fonctionnalités
→ Paramètres des fonctionnalités IA
Enter fullscreen mode Exit fullscreen mode

Ce paramètre est disponible dans le client Apidog 2.8.32+.

Quand un agent rencontre un blocage de permissions, demandez-lui de signaler le problème plutôt que de chercher une solution de contournement.

Pièges courants

  • Une mise à jour partielle a supprimé des champs.

    update remplace l’objet, il ne fusionne pas. Récupérez toujours l’objet complet, modifiez-le, validez-le, puis envoyez-le intégralement.

  • Une ressource existante n’a pas été importée dans la branche IA.

    Une branche IA démarre vide. Utilisez pick-to avant de modifier une ressource existante.

  • La mauvaise branche a été fournie à --from.

    Utilisez la branche principale ou une branche de sprint normale, jamais une branche générale.

  • La validation a été ignorée.

    cli-schema validate détecte les charges utiles mal formées avant l’appel d’API. Exécutez-la systématiquement.

  • Un changement cassant a été fusionné silencieusement.

    Imposez une étape de classification et exigez une approbation humaine explicite pour les changements cassants.

FAQ

  • Puis-je laisser un agent modifier directement la branche principale ?

    Oui, si vous activez les permissions de modification IA externes. Commencez toutefois par une branche IA : aucun changement n’atteint main avant validation.

  • Quelle est la différence entre branch merge et merge-request ?

    branch merge applique immédiatement les changements et requiert des permissions directes sur les deux branches. merge-request ouvre une demande de révision, adaptée aux branches principales protégées.

  • L’agent a-t-il besoin de l’application de bureau Apidog ?

    Non. La CLI est autonome. L’application est uniquement utile pour activer une fois les permissions de modification IA externes.

  • Comment éviter qu’un agent invente un nom de champ ?

    Utilisez systématiquement la boucle get → modification complète → validate → update. Une charge utile invalide échoue localement avant d’atteindre le projet.

En résumé

Pour laisser un agent mettre à jour une spécification d’API en sécurité :

  1. créez une branche IA isolée ;
  2. importez les ressources existantes avec pick-to ;
  3. appliquez la boucle lecture → modification → validation → écriture complète ;
  4. bloquez les changements cassants en attente d’approbation humaine ;
  5. révisez puis fusionnez uniquement les changements validés.

La CLI Apidog rend cette boucle scriptable et auditable. Un mauvais changement se supprime avec branch archive, sans mettre en danger la branche principale.

Téléchargez Apidog pour utiliser la CLI, puis combinez ce flux avec un agent capable de créer votre documentation API.

Top comments (0)