Modifier une spécification d'API à la main est un travail minutieux. Renommer un champ, ajouter une valeur d'énumération, renforcer un indicateur requis. Chaque changement est petit, mais chacun doit atterrir au bon endroit sans casser les points de terminaison qui le référencent. C'est précis, mécanique, et exactement le genre de tâche que vous confieriez à un agent IA, si seulement vous pouviez lui faire confiance pour ne pas détruire tout le schéma.
C'est possible. La CLI Apidog donne à un agent tout ce dont il a besoin pour modifier une spécification de manière responsable : validation du schéma avant chaque écriture, une branche isolée pour travailler, et une demande de fusion à réviser.
Ceci est le compagnon de mutation qui permet à un agent de créer de la documentation API. La création est additive et à faible risque ; la mise à jour d'un contrat existant est l'endroit où les garde-fous sont importants, donc la majeure partie de ce guide porte sur la façon de le faire sans rien casser.
Ce que signifie « mettre à jour la spécification » via la CLI
Votre spécification dans Apidog est l'ensemble des points de terminaison et des schémas de données d'un projet. La mettre à jour signifie l'une des trois commandes suivantes :
endpoint update: modifier un chemin, un paramètre, une réponse.schema update: modifier un modèle de données que les points de terminaison référencent.import: importer un nouveau fichier OpenAPI entier à concilier avec le projet.
Avant de confier l'un d'entre eux à un agent, vous devez comprendre deux comportements, car les mal comprendre est la façon dont une spécification est endommagée. Le premier est un modèle de permission, et le second est un piège qui supprime silencieusement des données.
Le piège qui vous mordra : la mise à jour est un remplacement complet
C'est la chose la plus importante à enseigner à votre agent. Les commandes update de la CLI ne sont pas un patch JSON. Elles soumettent directement les champs que vous fournissez ; elles ne fusionnent pas les éléments de tableau par ID. Si vous envoyez une mise à jour avec un tableau parameters partiel dans l'intention de modifier un seul paramètre, vous ne modifiez pas ce paramètre. Vous remplacez tout le tableau par celui que vous avez envoyé, et les autres sont supprimés.
La séquence correcte est toujours lecture-modification-écriture sur l'objet complet :
# 1. Obtenir la ressource complète actuelle
apidog endpoint get <endpointId> --project <projectId>
# 2. Modifier la structure complète localement (conserver tous les champs que vous ne modifiez pas)
# 3. Valider l'objet entier par rapport au schéma
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
Mettez cela dans les instructions de l'agent en termes simples : n'envoyez jamais un objet partiel à update ; récupérez toujours la ressource complète, modifiez-la et renvoyez-la entièrement. Un agent qui saute l'étape get supprimera silencieusement des champs. Un agent qui exécute cli-schema validate d'abord intercepte ses propres erreurs avant qu'elles n'atteignent le projet.
Le chemin sûr : laisser l'agent travailler sur une branche IA
Vous pourriez donner à l'agent une permission de modification directe sur votre branche principale. Ne le faites pas, du moins pas au début. Apidog dispose d'un mécanisme d'isolation spécialement conçu, la branche IA, pour exactement cela : un agent modifie des ressources sans toucher à la branche source, et rien n'est fusionné tant que vous ne l'avez pas dit. Considérez-le comme une demande de tirage pour votre spécification 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"
La convention de nommage est ai/AAAAJJ-de-source-fonctionnalité afin que l'origine et le but de la branche soient lisibles en un coup d'œil. La valeur --from doit être votre branche principale ou une branche de sprint normale, pas une branche générale. Un détail pratique : une branche IA sans différence par rapport à sa source est automatiquement archivée après 24 heures, de sorte que les expériences abandonnées se nettoient d'elles-mêmes.
Étape 2 : Importer les ressources que l'agent modifiera
Une branche IA commence vide. Elle ne clone pas automatiquement la branche source. Avant que l'agent ne puisse modifier un point de terminaison ou un schéma existant, extrayez cette ressource dans la branche avec pick-to :
apidog branch pick-to --project <projectId> --type ai \
--from main --to "ai/20260713-from-main-refund-fields" \
--endpoint-ids <ids>
Les ressources que l'agent crée directement sur la branche n'en ont pas besoin ; seulement celles existantes qu'il a l'intention de modifier ou de supprimer. C'est l'étape que les gens oublient : sautez-la, et l'agent aura une branche vide et rien à modifier.
Étape 3 : Laisser l'agent effectuer la modification
Maintenant, l'agent exécute la boucle lecture-modification-écriture précédente, mais avec --branch pointant vers la branche IA. Chaque modification est contenue :
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
Votre branche principale reste intacte pendant tout ce temps. Si l'agent se trompe, le rayon d'impact est une seule branche jetable.
Étape 4 : Réviser, puis fusionner
Les modifications des branches IA ne sont jamais réécrites automatiquement. Lorsque l'agent a terminé, vous décidez de ce qui se passe. Si la cible est protégée, ouvrez une demande de fusion plutôt que de fusionner directement :
apidog merge-request --help
apidog branch merge --project <projectId> --type ai \
--from "ai/20260713-from-main-refund-fields" --to main --endpoint-ids <ids>
Examinez le diff, approuvez, et le changement validé atterrit sur la branche principale. La fusion directe depuis la CLI nécessite une permission de modification directe sur les branches source et cible ; si la branche principale est protégée, préférez merge-request et approuvez-la dans le client Apidog.
Un exemple concret : renommer un champ en toute sécurité
Les règles abstraites sont faciles à accepter mais difficiles à appliquer. Voici un exemple concret. Supposons que vous souhaitiez renommer amount en amountCents sur le modèle de données Refund, car vous passez à des centimes entiers.
Vous dites à l'agent : « Renomme le champ amount du schéma Refund en amountCents et fais-en un entier. » Suivant ses règles, l'agent :
# 1. Récupérer le schéma COMPLET actuel sur la branche IA
apidog schema get <refundSchemaId> --project $PID --branch "ai/20260713-from-main-refund-fields"
Il récupère l'objet complet et modifie l'intégralité du jsonSchema, en conservant tous les champs qu'il ne touche pas :
{
"name": "Refund",
"jsonSchema": {
"type": "object",
"required": ["orderId", "amountCents"],
"properties": {
"orderId": { "type": "string" },
"amountCents": { "type": "integer" },
"reason": { "type": "string" }
}
}
}
Notez ce qui ne s'est pas produit : il n'a pas envoyé seulement la propriété modifiée. Il a envoyé le schéma entier avec orderId et reason intacts, car update remplace. Ensuite :
# 2. Valider l'objet complet
apidog cli-schema validate schema-create --file ./refund-full.json
# 3. Réécrire sur la branche IA
apidog schema update <refundSchemaId> --project $PID \
--branch "ai/20260713-from-main-refund-fields" --file ./refund-full.json
Vous examinez le diff de la branche IA (un champ renommé, rien d'autre n'est perturbé) et fusionnez. C'est toute la discipline : objet complet, validé, sur une branche, fusionné après examen.
Signaler les changements cassants avant de fusionner
Renommer un champ requis est un changement cassant : tout client envoyant amount échouera désormais à la validation. Un bon ensemble d'instructions pour l'agent fait en sorte que le modèle le signale plutôt que de fusionner silencieusement. Ajoutez ceci aux règles de l'agent :
Avant de fusionner tout changement de spécification, classez-le :
- Non cassant (nouveau champ optionnel, nouveau point de terminaison, contrainte assouplie) → résumer et procéder à la demande de fusion.
- Cassant (champ renommé/supprimé, nouveau champ requis, type renforcé) → ARRÊTER.
Signaler le changement cassant et les points de terminaison affectés, et attendre une approbation humaine explicite.
La branche IA est ce qui rend cela sûr à appliquer : parce que rien ne fusionne automatiquement, « arrêter et signaler » est un véritable point de contrôle, et non une course contre une écriture qui a déjà eu lieu.
Mettre à jour depuis un fichier OpenAPI à la place
Parfois, le changement existe déjà sous forme de fichier OpenAPI, généré à partir de code, édité ailleurs, ou transmis par une autre équipe. Plutôt que de rejouer les modifications champ par champ, l'agent peut importer le fichier pour le concilier avec le projet :
apidog import --project <projectId> --format openapi --file ./openapi.json \
--branch "ai/20260713-from-main-refund-fields"
import accepte OpenAPI 3.x, Swagger 2.0, Postman, et plus encore. Exécutez-le d'abord sur une branche IA afin de pouvoir examiner les changements de spécification entrants avant qu'ils n'atteignent la branche principale. Après la fusion, exportez la spécification réconciliée pour confirmer le résultat :
apidog export --project <projectId> --format openapi --oas-version 3.1 --output ./openapi.json
Cette approche est la meilleure lorsque la source de vérité se trouve en dehors d'Apidog et que vous la synchronisez. La méthode update champ par champ est la meilleure lorsque Apidog est la source de vérité et que vous effectuez un changement chirurgical.
Lorsque l'agent se trompe : revenir en arrière
La raison de travailler sur une branche IA est que les erreurs sont faciles à annuler. Si l'agent produit un changement que vous ne voulez pas, vous ne l'avez jamais fusionné, donc la branche principale est déjà correcte. Il suffit d'archiver la branche et de passer à autre chose :
apidog branch archive "ai/20260713-from-main-refund-fields" --project <projectId> --type ai
Parce qu'une branche IA sans différence acceptée s'auto-archive de toute façon après 24 heures, même une expérience oubliée se nettoie d'elle-même. Comparez cela à un agent modifiant directement la branche principale, où une mauvaise update est immédiatement en ligne et votre seul recours est la corbeille ou une annulation manuelle. La branche n'est pas de la bureaucratie ; c'est le bouton d'annulation.
Une note sur les permissions
Si une update ou un import est bloqué, le projet a les permissions de modification IA externes désactivées. C'est une barrière délibérée, et le flux de branche IA ci-dessus y répond : l'agent modifie une branche isolée et vous approuvez la fusion. Si vous préférez accorder des modifications directes, l'interrupteur se trouve dans Paramètres du projet → Paramètres des fonctionnalités → Paramètres des fonctionnalités IA (client Apidog 2.8.32+). Lorsqu'un agent rencontre un mur de permissions, ne le laissez pas choisir silencieusement une solution de contournement ; présentez le choix à un humain.
Pièges courants
- Mise à jour partielle ayant effacé des champs. L'erreur la plus dommageable et la plus courante.
updateremplace ; il ne fusionne pas. Récupérez l'objet complet, modifiez-le entièrement, validez, puis écrivez. Si un champ a disparu, l'agent a envoyé une charge utile partielle. - Modification d'une ressource existante sur une branche IA sans l'importer. La branche démarre vide.
pick-tola ressource en premier, sinon l'agent n'aura rien à modifier. - Mauvais
--frompour la branche IA. La source doit être la branche principale ou une branche de sprint, jamais une branche générale. La commandebranch createse plaindra si vous vous trompez. - Ignorer la validation.
cli-schema validatedétecte une charge utile mal formée sur votre machine. Un agent qui écrit sans valider transforme une faute de frappe en un appel d'API échoué, ou pire, en une mauvaise fusion. - Fusionner silencieusement un changement cassant. Sans une règle de classification préalable, un agent renommera volontiers un champ requis et le fusionnera. Faites de la détection des changements cassants un point de contrôle explicite.
FAQ
- Puis-je laisser l'agent modifier directement la branche principale ? Oui, en activant les permissions de modification IA externes, mais commencer sur une branche IA est plus sûr : rien n'atterrit sur la branche principale tant que vous n'avez pas approuvé une fusion. Réservez les modifications directes pour l'automatisation à faible risque et à haute confiance.
- Quelle est la différence entre
branch mergeetmerge-request?branch mergeapplique le changement immédiatement et nécessite une permission de modification directe sur les deux branches.merge-requestouvre une demande de révision, le bon choix lorsque la branche principale est protégée. - L'agent a-t-il besoin de l'application de bureau Apidog ? Non, la CLI est autonome. L'application n'est importante que pour activer le paramètre "Permissions de modification IA externes", qui est une configuration unique.
- Comment m'assurer que l'agent n'hallucine pas un nom de champ ? La boucle
cli-schema get→validateest le garde-fou. Une charge utile avec un champ inventé échoue à la validation localement, avant même d'atteindre le projet.
En résumé
Laisser un agent mettre à jour votre spécification d'API est sûr lorsque trois conditions sont remplies : il travaille sur une branche IA isolée, il traite chaque mise à jour comme une lecture-modification-écriture complète plutôt que comme un patch, et un humain approuve la fusion. La CLI Apidog vous offre ces trois éléments sous forme de commandes, ce qui signifie que toute la boucle (modifier, valider, réviser) est scriptable et auditable, et qu'un mauvais changement est à un archive de la suppression.
Configurez la branche IA, donnez à l'agent la règle de lecture-modification-écriture et le point de contrôle des changements cassants, et la maintenance de la spécification devient un diff que vous approuvez au lieu d'un travail fastidieux que vous continuez à repousser. Téléchargez Apidog pour obtenir la CLI, et associez cela à laisser un agent créer votre documentation pour couvrir la boucle complète d'édition et de maintenance.