DEV Community

Cover image for Cómo permitir que un agente de IA actualice tu especificación API con la CLI de Apidog
Roobia
Roobia

Posted on • Originally published at apidog.com

Cómo permitir que un agente de IA actualice tu especificación API con la CLI de Apidog

Editar una especificación de API manualmente es una tarea precisa y repetitiva: renombrar campos, añadir valores de enumeración o ajustar propiedades obligatorias. La CLI de Apidog permite delegar estos cambios a un agente de IA sin perder control: valida antes de escribir, trabaja en una rama aislada y deja la fusión pendiente de revisión humana.

Prueba Apidog hoy

Este flujo complementa la capacidad de permitir que un agente cree documentación de API. Crear recursos suele ser aditivo; modificar un contrato existente requiere controles para evitar eliminar campos o introducir cambios disruptivos.

Qué significa actualizar una especificación con la CLI

En Apidog, una especificación reúne los endpoints y esquemas de datos de un proyecto. Puedes actualizarla mediante tres comandos:

  • endpoint update: modifica una ruta, parámetro o respuesta.
  • schema update: modifica un modelo de datos referenciado por endpoints.
  • import: importa un archivo OpenAPI completo para conciliarlo con el proyecto.

Antes de automatizar cualquiera de estos comandos, ten en cuenta dos reglas:

  1. Las actualizaciones reemplazan recursos completos.
  2. Los cambios deben hacerse en una rama de IA antes de llegar a la rama principal.

Regla crítica: update reemplaza, no fusiona

Los comandos update no funcionan como JSON Patch. Si envías un array parcial de parameters, la CLI no actualiza solo ese parámetro: reemplaza el array completo y elimina los parámetros que no incluiste.

Usa siempre el ciclo leer → modificar → validar → escribir sobre el objeto completo:

# 1. Obtener el recurso completo
apidog endpoint get <endpointId> --project <projectId>

# 2. Editar localmente la estructura completa.
# Conserva todos los campos que no quieres modificar.

# 3. Validar el objeto completo contra el esquema de la CLI
apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file ./endpoint-full.json

# 4. Escribir de nuevo el recurso completo
apidog endpoint update <endpointId> --project <projectId> --file ./endpoint-full.json
Enter fullscreen mode Exit fullscreen mode

Incluye esta instrucción explícitamente en el prompt o las reglas de tu agente:

Nunca envíes un objeto parcial a update. Recupera el recurso completo, modifícalo localmente, valídalo y vuelve a enviarlo completo.

Si el agente omite get, puede eliminar campos silenciosamente. Si ejecuta cli-schema validate antes de escribir, detecta errores de estructura antes de que lleguen al proyecto.

Flujo seguro: usar una rama de IA

No empieces dando acceso directo a la rama principal. Usa una rama de IA para aislar el trabajo del agente: los cambios no se fusionan hasta que una persona los revisa y aprueba.

Paso 1: crear la rama de IA 

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

Usa una convención como:

ai/AAAA-MM-DD-origen-característica
Enter fullscreen mode Exit fullscreen mode

El valor de --from debe ser la rama principal o una rama de sprint normal, no una rama general. Las ramas de IA sin diferencias respecto a su origen se autoarchivan después de 24 horas.

Paso 2: llevar los recursos existentes a la rama

Una rama de IA empieza vacía: no clona automáticamente los recursos de origen. Antes de editar un endpoint o esquema existente, llévalo 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>
Enter fullscreen mode Exit fullscreen mode

Solo necesitas este paso para recursos existentes que el agente vaya a modificar o eliminar. Los recursos nuevos pueden crearse directamente en la rama.

Paso 3: ejecutar el ciclo leer-modificar-escribir

Indica la rama con --branch en cada operación:

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 rama principal permanece intacta. Si el agente comete un error, el impacto queda contenido en una rama desechable.

Paso 4: revisar y fusionar

Los cambios de una rama de IA no se escriben automáticamente en el destino. Si la rama principal está protegida, usa una solicitud de fusión:

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

Revisa el diff antes de aprobarlo. La fusión directa con branch merge requiere permiso de edición directa en las ramas de origen y destino. Para una rama principal protegida, usa merge-request y apruébalo desde el cliente de Apidog.

Ejemplo: renombrar un campo sin perder propiedades

Supongamos que debes renombrar amount a amountCents en el esquema Refund, porque el valor pasará a expresarse en céntimos enteros.

Primero, recupera el esquema completo desde la rama de IA:

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

Después, edita el jsonSchema completo. No envíes únicamente la propiedad modificada:

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

Observa que orderId y reason permanecen en la carga útil. Esto es obligatorio porque update reemplaza el recurso.

Valida y actualiza en la rama aislada:

# 1. Validar el objeto completo
apidog cli-schema validate schema-create --file ./refund-full.json

# 2. Actualizar el esquema en la rama de IA
apidog schema update <refundSchemaId> --project $PID \
  --branch "ai/20260713-from-main-refund-fields" \
  --file ./refund-full.json
Enter fullscreen mode Exit fullscreen mode

Finalmente, revisa el diff. Deberías ver únicamente el cambio esperado: amount pasa a ser amountCents y cambia a integer.

Bloquear cambios disruptivos antes de fusionar

Renombrar un campo obligatorio es un cambio disruptivo. Los clientes que sigan enviando amount fallarán la validación.

Añade una regla de clasificación al conjunto de instrucciones del agente:

Antes de fusionar cualquier cambio en la especificación, clasifícalo:

- No disruptivo: nuevo campo opcional, nuevo endpoint o restricción flexibilizada.
  → Resumir el cambio y proceder a la solicitud de fusión.

- Disruptivo: campo renombrado o eliminado, nuevo campo obligatorio o tipo ajustado.
  → DETENER.
  Informar del cambio disruptivo y de los endpoints afectados.
  Esperar aprobación humana explícita.
Enter fullscreen mode Exit fullscreen mode

La rama de IA convierte esta regla en un control real: el agente puede preparar y validar el cambio, pero no llega a producción sin aprobación.

Actualizar desde un archivo OpenAPI

Si el cambio ya existe en un archivo OpenAPI —por ejemplo, generado desde código o mantenido por otro equipo— puedes importarlo en lugar de reconstruir cada modificación campo por campo:

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

import acepta OpenAPI 3.x, Swagger 2.0, Postman y otros formatos. Ejecútalo primero en una rama de IA para revisar el impacto antes de fusionar.

Después de la fusión, exporta la especificación conciliada para comprobar el resultado:

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

Usa import cuando la fuente de la verdad esté fuera de Apidog. Usa endpoint update o schema update cuando Apidog sea la fuente de la verdad y necesites un cambio puntual.

Revertir cambios del agente

Si el resultado no es correcto y aún no se ha fusionado, la rama principal no necesita ninguna reparación. Simplemente archiva la rama de IA:

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

Además, una rama de IA sin diferencias aceptadas se autoarchiva después de 24 horas. La rama funciona como un botón de deshacer para cambios de especificación.

Permisos de edición

Si update o import devuelven un error de permisos, es posible que los Permisos de Edición Externa de IA estén desactivados en el proyecto.

El flujo con rama de IA está diseñado para ese escenario: el agente edita una rama aislada y una persona aprueba la fusión. Si necesitas habilitar ediciones directas, la opción está en:

Configuración del Proyecto
→ Configuración de Características
→ Configuración de Características de IA
Enter fullscreen mode Exit fullscreen mode

Esta configuración está disponible en el cliente de Apidog 2.8.32+. Si el agente encuentra un bloqueo de permisos, debe informar la situación y pedir una decisión humana, no buscar una alternativa silenciosa.

Errores comunes

Enviar una actualización parcial

update reemplaza; no fusiona. Recupera el objeto completo, edítalo, valídalo y envíalo completo.

Editar una rama de IA vacía

Las ramas de IA no contienen automáticamente los recursos de origen. Usa pick-to antes de modificar recursos existentes.

Usar un origen incorrecto en --from

La rama de origen debe ser la principal o una rama de sprint normal, nunca una rama general.

Omitir cli-schema validate

La validación detecta cargas útiles mal formadas localmente. Sin este paso, un error tipográfico puede convertirse en una llamada fallida o una fusión defectuosa.

Fusionar cambios disruptivos sin avisar

Un campo requerido renombrado o eliminado puede romper clientes existentes. Obliga al agente a clasificar cambios y a detenerse ante modificaciones disruptivas.

Preguntas frecuentes

¿Puedo permitir que el agente edite main directamente?

Sí, habilitando los Permisos de Edición Externa de IA. Sin embargo, una rama de IA es más segura porque ningún cambio llega a main hasta que apruebes la fusión.

¿Cuál es la diferencia entre branch merge y merge-request?

branch merge aplica los cambios inmediatamente y requiere permisos de edición directa. merge-request abre una solicitud revisable, adecuada cuando la rama principal está protegida.

¿El agente necesita la aplicación de escritorio de Apidog?

No. La CLI funciona de forma independiente. La aplicación solo es necesaria para activar una vez la configuración de Permisos de Edición Externa de IA.

¿Cómo evito que el agente invente nombres de campos?

Usa el ciclo get → cli-schema validate → update. Una carga útil con un campo inventado falla la validación local antes de llegar al proyecto.

Conclusión

Automatizar actualizaciones de especificaciones de API con un agente es seguro si aplicas tres controles:

  1. Trabaja en una rama de IA aislada.
  2. Trata cada update como una operación completa de leer-modificar-escribir.
  3. Exige revisión humana antes de fusionar, especialmente ante cambios disruptivos.

Configura la rama, entrega al agente estas reglas y convierte el mantenimiento de la especificación en un diff revisable y auditable. Descarga Apidog para usar la CLI y combínalo con la automatización para crear documentación de API y cubrir tanto la creación como el mantenimiento del contrato.

Top comments (0)