Editar una especificación de API a mano es un trabajo minucioso. Renombrar un campo, añadir un valor de enumeración, ajustar una bandera de requerido. Cada cambio es pequeño, pero cada uno debe aterrizar en el lugar correcto sin romper los puntos finales que lo referencian. Es preciso, mecánico y exactamente el tipo de tarea que le confiarías a un agente de IA, si tan solo pudieras confiar en que no destrozaría todo el esquema.
Puedes hacerlo. La CLI de Apidog le da a un agente todo lo que necesita para cambiar una especificación de manera responsable: validación de esquema antes de cada escritura, una rama aislada para trabajar y una solicitud de fusión para que la revises.
Este es el complemento de mutación para permitir que un agente cree documentación de API. Crear es aditivo y de bajo riesgo; actualizar un contrato existente es donde las barandillas de seguridad son importantes, por lo que la mayor parte de esta guía trata sobre cómo hacerlo sin romper nada.
Lo que significa "actualizar la especificación" en la CLI
Tu especificación en Apidog es el conjunto de puntos finales y esquemas de datos en un proyecto. Actualizarla significa uno de estos tres comandos:
endpoint update: cambiar una ruta, un parámetro, una respuesta.schema update: cambiar un modelo de datos al que hacen referencia los puntos finales.import: importar un nuevo archivo OpenAPI completo para conciliar con el proyecto.
Antes de dirigir un agente a cualquiera de ellos, hay dos comportamientos que debes comprender, porque equivocarse con ellos es cómo se daña una especificación. El primero es un modelo de permisos y el segundo es una trampa que elimina datos silenciosamente.
La trampa que te morderá: la actualización es un reemplazo completo
Esto es lo más importante que debes enseñarle a tu agente. Los comandos `update` de la CLI **no** son JSON Patch. Envían los campos que proporcionas directamente; no fusionan elementos de array por ID. Si envías una actualización con un array `parameters` parcial con la intención de cambiar un parámetro, no editas ese parámetro. Reemplazas todo el array con solo el que enviaste, y el resto desaparece.
La secuencia correcta es siempre leer-modificar-escribir sobre el objeto *completo*:
# 1. Obtener el recurso completo actual
apidog endpoint get <endpointId> --project <projectId>
# 2. Editar la estructura completa localmente (mantener todos los campos que no se están cambiando)
# 3. Validar el objeto completo contra el esquema
apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file ./endpoint-full.json
# 4. Volver a escribir el objeto completo
apidog endpoint update <endpointId> --project <projectId> --file ./endpoint-full.json
Pon esto en las instrucciones del agente en términos sencillos: *nunca envíes un objeto parcial a `update`; siempre recupera el recurso completo, modifícalo y envíalo de nuevo entero.* Un agente que omita el paso `get` eliminará campos silenciosamente. Un agente que ejecuta `cli-schema validate` primero detecta sus propios errores antes de que lleguen al proyecto.
La ruta segura: deja que el agente trabaje en una rama de IA
Podrías darle al agente permiso de edición directa en tu rama principal. No lo hagas, al menos no para empezar. Apidog tiene un mecanismo de aislamiento especialmente diseñado, la **rama de IA**, diseñado exactamente para esto: un agente modifica recursos sin tocar la rama de origen, y nada se fusiona hasta que tú lo digas. Piénsalo como una solicitud de extracción para tu especificación de API.
Paso 1: Crear la rama de IA
apidog branch create --project <projectId> --type ai \
--from main --name "ai/20260713-from-main-refund-fields"
La convención de nombres es `ai/AAAA-MM-DD-de-origen-característica` para que el origen y el propósito de la rama sean legibles de un vistazo. El valor `--from` debe ser tu rama principal o una rama de sprint normal, no una rama general. Un detalle útil: una rama de IA sin diferencia con respecto a su origen se autoarchiva después de 24 horas, por lo que los experimentos abandonados se limpian solos.
Paso 2: Importar los recursos que editará el agente
Una rama de IA comienza vacía. No clona la rama de origen automáticamente. Antes de que el agente pueda editar un punto final o esquema *existente*, trae ese recurso a la rama con `pick-to`:
apidog branch pick-to --project <projectId> --type ai \
--from main --to "ai/20260713-from-main-refund-fields" \
--endpoint-ids <ids>
Los recursos que el agente *crea* nuevos en la rama no necesitan esto; solo los existentes que pretende modificar o eliminar. Este es el paso que la gente olvida: omítelo y el agente tendrá una rama vacía y nada que editar.
Paso 3: Deja que el agente haga el cambio
Ahora el agente ejecuta el bucle de leer-modificar-escribir de antes, pero con `--branch` apuntando a la rama de IA. Cada edición está contenida:
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
Tu rama principal permanece intacta todo este tiempo. Si el agente se equivoca en algo, el radio de explosión es una rama desechable.
Paso 4: Revisar, luego fusionar
Los cambios en la rama de IA nunca se escriben automáticamente. Cuando el agente termina, *tú* decides qué sucede. Si el objetivo está protegido, abre una solicitud de fusión en lugar de fusionar directamente:
apidog merge-request --help
apidog branch merge --project <projectId> --type ai \
--from "ai/20260713-from-main-refund-fields" --to main --endpoint-ids <ids>
Revisa la diferencia, aprueba, y el cambio verificado se aplica a la rama principal. La fusión directa desde la CLI requiere permiso de edición directa en ambas ramas de origen y destino; si la rama principal está protegida, prefiere `merge-request` y apruébalo en el cliente de Apidog.
Un ejemplo práctico: cambiar el nombre de un campo de forma segura
Las reglas abstractas son fáciles de asentir, pero difíciles de aplicar. Aquí tienes una concreta. Supongamos que quieres cambiar el nombre de `amount` a `amountCents` en el modelo de datos `Refund`, porque estás pasando a céntimos enteros.
Le dices al agente: *“Renombra el campo `amount` en el esquema Refund a `amountCents` y hazlo un entero.”* Siguiendo sus reglas, el agente:
# 1. Obtener el esquema COMPLETO actual en la rama de IA
apidog schema get <refundSchemaId> --project $PID --branch "ai/20260713-from-main-refund-fields"
Recupera el objeto completo y edita todo el `jsonSchema`, manteniendo cada campo que no está tocando:
{
"name": "Refund",
"jsonSchema": {
"type": "object",
"required": ["orderId", "amountCents"],
"properties": {
"orderId": { "type": "string" },
"amountCents": { "type": "integer" },
"reason": { "type": "string" }
}
}
}
Fíjate en lo que *no* sucedió: no envió solo la propiedad cambiada. Envió el esquema completo con `orderId` y `reason` intactos, porque `update` reemplaza. Luego:
# 2. Validar el objeto completo
apidog cli-schema validate schema-create --file ./refund-full.json
# 3. Volver a escribirlo en la rama de IA
apidog schema update <refundSchemaId> --project $PID \
--branch "ai/20260713-from-main-refund-fields" --file ./refund-full.json
Revisas la diferencia de la rama de IA (un campo renombrado, nada más se vio alterado) y fusionas. Esa es toda la disciplina: objeto completo, validado, en una rama, fusionado después de la revisión.
Señalar cambios disruptivos antes de fusionar
Cambiar el nombre de un campo requerido es un cambio disruptivo: cualquier cliente que envíe `amount` ahora fallará la validación. Un buen conjunto de instrucciones para el agente hace que el modelo *lo diga* en lugar de fusionarse silenciosamente. Añade esto a las reglas del agente:
Antes de fusionar cualquier cambio en la especificación, clasifícalo:
- No disruptivo (nuevo campo opcional, nuevo punto final, restricción flexibilizada) → resumir y proceder a la solicitud de fusión.
- Disruptivo (campo renombrado/eliminado, nuevo campo requerido, tipo ajustado) → DETENER.
Informar el cambio disruptivo y los puntos finales afectados, y esperar la aprobación humana explícita.
La rama de IA es lo que hace que esto sea seguro de aplicar: como nada se fusiona automáticamente, "detener e informar" es un punto de control real, no una carrera contra una escritura que ya ocurrió.
Actualizar desde un archivo OpenAPI en su lugar
A veces, el cambio ya existe como un archivo OpenAPI, generado a partir de código, editado en otro lugar o entregado por otro equipo. En lugar de reproducir las ediciones campo por campo, el agente puede importar el archivo para conciliarlo con el proyecto:
apidog import --project <projectId> --format openapi --file ./openapi.json \
--branch "ai/20260713-from-main-refund-fields"
`import` acepta OpenAPI 3.x, Swagger 2.0, Postman y más. Ejecútalo primero en una rama de IA para que puedas revisar qué cambia la especificación entrante antes de que llegue a la rama principal. Después de fusionar, exporta la especificación conciliada de nuevo para confirmar el resultado:
apidog export --project <projectId> --format openapi --oas-version 3.1 --output ./openapi.json
Esta ruta es la mejor cuando la fuente de la verdad reside fuera de Apidog y la estás sincronizando. La ruta `update` por campo es la mejor cuando Apidog *es* la fuente de la verdad y estás haciendo un cambio quirúrgico.
Cuando el agente se equivoca: reversión
La razón para trabajar en una rama de IA es que los errores son baratos de deshacer. Si el agente produce un cambio que no quieres, nunca lo fusionaste, por lo que la rama principal ya es correcta. Simplemente archiva la rama y sigue adelante:
apidog branch archive "ai/20260713-from-main-refund-fields" --project <projectId> --type ai
Debido a que una rama de IA sin diferencia aceptada se autoarchiva después de 24 horas de todos modos, incluso un experimento olvidado se limpia solo. Compara eso con un agente editando la rama principal directamente, donde una `update` mala está en vivo inmediatamente y tu único recurso es la papelera de reciclaje o una reversión manual. La rama no es burocracia; es el botón de deshacer.
Una nota sobre los permisos
Si una `update` o `import` vuelve bloqueada, el proyecto tiene los Permisos de Edición Externa de IA desactivados. Esa es una barrera deliberada, y el flujo de rama de IA anterior es la respuesta a ello: el agente edita una rama aislada y tú apruebas la fusión. Si prefieres otorgar ediciones directas, el interruptor se encuentra en Configuración del Proyecto → Configuración de Características → Configuración de Características de IA (cliente Apidog 2.8.32+). Cuando un agente se encuentra con un muro de permisos, no lo hagas buscar una solución alternativa silenciosamente; presenta la elección a un humano.
Errores comunes
La actualización parcial borró campos. El error más dañino y común. `update` reemplaza; no fusiona. Obtén el objeto completo, edítalo por completo, valida y luego escribe. Si un campo desapareció, el agente envió una carga útil parcial.
Editar un recurso existente en una rama de IA sin importarlo. La rama comienza vacía. Primero, `pick-to` el recurso, o el agente no tendrá nada que editar.
`--from` incorrecto para la rama de IA. La fuente debe ser la rama principal o una rama de sprint, nunca una rama general. El comando `branch create` se quejará si te equivocas.
Omitir la validación. `cli-schema validate` detecta una carga útil mal formada en tu máquina. Un agente que escribe sin validar convierte un error tipográfico en una llamada a la API fallida, o peor, en una fusión defectuosa.
Fusionar un cambio disruptivo silenciosamente. Sin una regla de clasificación previa, un agente renombrará alegremente un campo requerido y lo fusionará. Haz de la detección de cambios disruptivos un punto de control explícito.
Preguntas frecuentes
¿Puedo permitir que el agente edite la rama principal directamente? Puedes, habilitando los Permisos de Edición Externa de IA, pero empezar en una rama de IA es más seguro: nada llega a la rama principal hasta que apruebes una fusión. Reserva las ediciones directas para automatizaciones de bajo riesgo y alta confianza.
¿Cuál es la diferencia entre `branch merge` y `merge-request`? `branch merge` aplica el cambio inmediatamente y necesita permiso de edición directa en ambas ramas. `merge-request` abre una solicitud revisable, la opción correcta cuando la rama principal está protegida.
¿Necesita el agente la aplicación de escritorio de Apidog? No, la CLI es independiente. La aplicación solo importa para activar la configuración de Permisos de Edición Externa de IA, que es una configuración única.
¿Cómo me aseguro de que el agente no "alucine" un nombre de campo? El bucle `cli-schema get` → `validate` es la barandilla de seguridad. Una carga útil con un campo inventado falla la validación localmente, antes de que llegue al proyecto.
Conclusión
Permitir que un agente actualice tu especificación de API es seguro cuando se cumplen tres condiciones: trabaja en una rama de IA aislada, trata cada actualización como una operación completa de leer-modificar-escribir en lugar de un parche, y un humano aprueba la fusión. La CLI de Apidog te ofrece las tres como comandos, lo que significa que todo el bucle (editar, validar, revisar) es automatizable y auditable, y un cambio erróneo está a un `archive` de desaparecer.
Configura la rama de IA, entrega al agente la regla de leer-modificar-escribir y el punto de control de cambios disruptivos, y el mantenimiento de la especificación se convierte en una diferencia que apruebas en lugar de un trabajo minucioso que sigues posponiendo. Descarga Apidog para obtener la CLI, y combina esto con dejar que un agente cree tu documentación para cubrir el ciclo completo de autoría y mantenimiento.