Cómo hacer que un agente de IA cree documentación de API con el CLI de Apidog

La documentación de la API es la tarea que todos concuerdan que es importante y que nadie quiere asumir. Se lanza un nuevo endpoint, la referencia se retrasa una semana y la guía de inicio rápido describe un flujo de autenticación que reemplazaste hace dos sprints. El trabajo es real, pero es repetitivo y fácil de posponer.

Esa combinación (importante, repetitiva, posponible) es exactamente para lo que sirve un agente de IA. Si tu agente puede ejecutar un comando de terminal, puede crear endpoints, escribir las guías en prosa a su alrededor y publicar un sitio de documentación, todo a partir de una solicitud en lenguaje natural. La CLI de Apidog es lo que lo hace posible: cada acción de documentación es un comando programable con una salida JSON estructurada que un agente puede leer y sobre la cual puede actuar.

Por qué la CLI, no la GUI o un servidor MCP

Hay tres formas en que un agente puede interactuar con la documentación de tu API, y resuelven diferentes problemas. Acertar con esta distinción es la diferencia entre luchar con tus herramientas y usar la adecuada para el trabajo.

Un servidor MCP es excelente cuando quieres que un agente lea tu definición de API y genere código cliente a partir de ella. El flujo de documentación a través de MCP de Cursor es el ejemplo canónico. Pero eso es lo contrario de lo que queremos aquí. Queremos que el agente produzca la documentación: cree endpoints, escriba guías en Markdown y publique un sitio.

Para eso, la CLI gana por tres motivos. Es determinista: el mismo comando produce el mismo resultado. Es programable: todo el flujo se integra en CI. Y devuelve JSON en cada llamada, incluyendo un campo `agentHints.nextSteps` que le indica al agente qué puede hacer a continuación. Este último punto importa más de lo que parece: significa que el agente no está adivinando su camino, sino que sigue las propias sugerencias de la CLI.

Configura el entorno del agente

Instala la CLI y autentícate una vez. Nuestra guía de instalación cubre las versiones de Node y PATH; la guía de autenticación cubre los tokens y secretos de CI.

npm install -g apidog-cli
apidog login --with-token <TOKEN>

Obtén el token de la aplicación Apidog en avatar de usuario → Configuración de la cuenta → Token de acceso a la API. Se almacena localmente después del inicio de sesión, por lo que el agente no lo pasa en cada llamada.

Cada escritura se realiza contra un ID de proyecto, que encontrarás en Configuración del proyecto → Configuración básica, o ejecutando:

apidog project list

Cualquier agente de codificación que pueda ejecutar comandos de shell funciona aquí: Claude Code, Cursor, Codex y otros. A la CLI no le importa cuál lo está llamando; solo le importa que los comandos y las cargas útiles sean correctos. Lo que nos lleva a la única regla que hace que todo sea fiable.

El ritual de escritura que un agente debe seguir

Los comandos de documentación que crean recursos toman un archivo JSON. Tu agente nunca debe construir ese JSON de memoria. Los nombres de campo inventados por el modelo son la causa número uno de fallos. La CLI envía el esquema exacto para cada escritura, y la secuencia correcta es siempre la misma en cuatro pasos:

# 1. Pregunta a la CLI cómo es la carga útil
apidog cli-schema get doc-create

# 2. Genera el archivo JSON a partir de ese esquema

# 3. Valida antes de escribir (detecta un campo faltante localmente)
apidog cli-schema validate doc-create --file ./doc.json

# 4. Solo ahora ejecuta el comando real
apidog doc create --project <projectId> --file ./doc.json

Integra este bucle en las instrucciones del agente. Convierte "el modelo inventó un campo" en "el validador lo rechazó en mi máquina", que es la diferencia entre una ejecución limpia y una compilación fallida. Aquí tienes un bloque de reglas que puedes pegar directamente en el prompt del sistema de un agente o en un archivo `CLAUDE.md` / `.cursorrules`:

Reglas de la CLI de Apidog:
- Nunca escribas una carga útil JSON a mano. Primero, ejecuta `apidog cli-schema get <key>` y construye a partir de ese esquema.
- Valida cada archivo con `apidog cli-schema validate <key> --file <path>` antes de cualquier creación o actualización.
- Siempre pasa --project <id> en los comandos de escritura.
- Lee el campo `agentHints.nextSteps` en cada respuesta JSON para elegir el siguiente comando.
- Si una escritura es bloqueada por permisos, detente y pregunta al humano; no busques una solución alternativa.

Esas cinco líneas son lo que diferencia a un agente que entrega documentación de forma fiable de uno que adivina cargas útiles y falla.

Paso 1: Crea la referencia a partir de endpoints y esquemas

En Apidog, tu referencia de API se genera a partir de los endpoints y esquemas de datos del proyecto. Así que la primera tarea del agente es crearlos. Supongamos que le dices:

“Añade un endpoint POST /refunds que reciba un ID de pedido y un importe, y documenta sus respuestas de éxito y de error de validación.”

El agente crea primero el modelo de datos reutilizable, luego el endpoint que lo referencia. Ejecutando `apidog cli-schema get schema-create` muestra que un esquema de datos toma un `name` y un objeto `jsonSchema` estándar. Así que el agente escribe algo como `refund-schema.json`:

{
  "name": "Refund",
  "description": "A refund issued against an order",
  "jsonSchema": {
    "type": "object",
    "required": ["orderId", "amount"],
    "properties": {
      "orderId": { "type": "string" },
      "amount": { "type": "number" },
      "reason": { "type": "string" }
    }
  }
}

Valida y crea:

apidog cli-schema validate schema-create --file ./refund-schema.json
apidog schema create --project <projectId> --file ./refund-schema.json

Ahora el endpoint. El esquema `endpoint-create` requiere `method` y `path`, y te permite referenciar el modelo de datos que acabas de crear con un `$ref` en el formato `#/definitions/{schemaId}`. El agente escribe `refunds-endpoint.json`:

{
  "name": "Create refund",
  "method": "post",
  "path": "/refunds",
  "status": "developing",
  "requestBody": {
    "type": "application/json",
    "jsonSchema": { "$ref": "#/definitions/<refundSchemaId>" }
  }
}

apidog cli-schema validate endpoint-create --file ./refunds-endpoint.json
apidog endpoint create --project <projectId> --file ./refunds-endpoint.json

La documentación de referencia para `/refunds` ahora existe, renderizada a partir de la misma definición que tu equipo edita. No hay un paso separado de "exportar la documentación" para la referencia; está en vivo en el proyecto en el momento en que se crea el endpoint. Esa es la recompensa de una fuente "schema-first": la referencia no puede desfasarse, porque *es* el esquema.

Paso 2: Escribe las guías, no solo la referencia

Una referencia generada a partir de esquemas es solo la mitad de una buena documentación. La otra mitad es prosa: una página de inicio, un tutorial de autenticación, una nota de migración. En Apidog, estos residen en el árbol de documentos del proyecto como documentos Markdown, gestionados por el grupo de comandos `doc`.

El esquema `doc-create` solo requiere un `name`; `content` contiene el Markdown, y `folderId` lo coloca en el árbol (`0` es la raíz). Así, un inicio rápido que el agente redacta se convierte en `quickstart.json`:

{
  "name": "Quickstart: Your first refund",
  "content": "# Quickstart\n\nThis guide takes you from API key to your first refund in five minutes...",
  "folderId": 0
}

apidog doc list --project <projectId>
apidog cli-schema validate doc-create --file ./quickstart.json
apidog doc create --project <projectId> --file ./quickstart.json

Aquí es donde el agente se gana el sueldo. Pídele que "escriba un inicio rápido que guíe a un nuevo desarrollador desde la clave de API hasta el primer reembolso", y redacta el Markdown, lo envuelve en la carga útil que espera el esquema, valida y crea el documento. Sin navegador, sin copiar y pegar. Debido a que el contenido es solo un campo de cadena, el agente puede escribir una guía tan larga o detallada como la tarea lo requiera.

Paso 3: Publica el sitio de documentación

Con la referencia y las guías en su lugar, el agente también puede publicar desde la terminal. Dos grupos de comandos manejan esto, y una distinción de nombres confunde a la gente constantemente:

• `doc`: un documento Markdown *dentro* del árbol de la API del proyecto (lo que creaste en el paso 2).
• `docs-site`: el sitio de documentación público y alojado.
• `shared-doc`: un enlace compartible para entregar a un socio, no un sitio completo.

apidog docs-site list --project <projectId>
apidog cli-schema get docs-site-create
apidog docs-site create --project <projectId> --file ./docs-site.json

Usa `docs-site` cuando quieras un sitio público definido desde la terminal, y `shared-doc` cuando solo necesites un enlace para enviar a alguien. Dado que ambos son comandos, la publicación se convierte en un paso programado que el agente ejecuta después de cada cambio de documento; el sitio alojado refleja la actualización en el momento en que el comando regresa.

Paso 4 (opcional): Exporta una copia portable

A veces quieres la documentación como un archivo: una página HTML para alojar en otro lugar, Markdown para un generador de sitios estáticos o OpenAPI para entregar a otros. El comando `export` produce los tres:

apidog export --project <projectId> --format html --output ./api-docs.html
apidog export --project <projectId> --format markdown --output ./api-docs.md
apidog export --project <projectId> --format openapi --oas-version 3.1 --output ./openapi.json

Si tu proyecto contiene varios servicios y solo quieres documentar una parte, `apidog export --help` muestra las banderas `--scope`, `--api-ids` y `--folder-ids` para restringir la salida. De esta manera, un solo proyecto puede enviar un archivo de documentación por cada servicio.

Un ejemplo completo, de principio a fin

Aquí está el ciclo completo como una solicitud en lenguaje natural y los comandos que un agente ejecuta para satisfacerla.

Tú: “Acabamos de añadir un servicio de pagos con POST /refunds y GET /refunds/{id}. Documenta ambos, escribe una breve guía explicando las claves de idempotencia y publícala en nuestro sitio de documentación.”

El agente, siguiendo sus reglas, ejecuta:

# Crea el modelo de datos compartido
apidog cli-schema validate schema-create --file ./refund-schema.json
apidog schema create --project $PID --file ./refund-schema.json

# Crea ambos endpoints
apidog endpoint create --project $PID --file ./post-refunds.json
apidog endpoint create --project $PID --file ./get-refund.json

# Escribe la guía de idempotencia como un documento Markdown
apidog doc create --project $PID --file ./idempotency-guide.json

# Publica
apidog docs-site create --project $PID --file ./docs-site.json

Revisas el diff resultante, y el servicio de pagos está documentado y en vivo. Lo que solía ser una tarde de cambio de contexto, ahora es una solicitud y una revisión.

Intégralo en un bucle de agente o CI

Debido a que cada paso es un comando, todo el flujo se integra en CI o en el bucle de tareas de un agente. Un paso mínimo que regenera y confirma tu referencia Markdown en cada push:

- name: Regenerar documentos de API
  run: |
    npm install -g apidog-cli
    apidog login --with-token ${{ secrets.APIDOG_TOKEN }}
    apidog export --project ${{ secrets.APIDOG_PROJECT }} --format markdown --output ./docs/api-docs.md

Para una imagen más completa de cómo ejecutar un agente con la CLI de principio a fin, consulta Del PRD al ciclo de pruebas y Cómo configurar 5 agentes de IA para construir una API completa. El patrón en ambos es el mismo que aquí: describir la intención, dejar que el agente la traduzca en llamadas a la CLI validadas, revisar el resultado.

Una nota sobre permisos

La escritura en un proyecto a través de un agente puede estar protegida. Si un comando `create` es bloqueado, el proyecto tiene los permisos de edición externa por IA desactivados para esa rama. Tienes dos opciones honestas: habilitar el permiso de edición directa en Configuración del proyecto → Configuración de funciones → Configuración de funciones de IA (cliente Apidog 2.8.32+), o hacer que el agente trabaje en una rama de IA aislada y abra una solicitud de fusión. La guía complementaria sobre cómo actualizar tu especificación de API describe el flujo de la rama de IA en su totalidad, y se aplica igualmente cuando el agente está *creando* documentación en una rama protegida.

Inconvenientes comunes

El agente construyó el JSON a mano. Esta es la falla número uno. Refuerza `cli-schema get` → `cli-schema validate` → `create` en las instrucciones del agente para que trabaje con el esquema real, no con uno adivinado.

Falta el ID del proyecto. Cada llamada a `doc`, `docs-site` y `export` necesita `--project`, el ID de la configuración, no el nombre legible del proyecto. La mayoría de los informes de "hubo un error" se deben a esto.

Confundir `doc`, `docs-site` y `shared-doc`. Son tres cosas diferentes: una página Markdown en el árbol, un sitio alojado y un enlace para compartir. Haz que el agente confirme cuál significa la tarea antes de escribir.

Token no configurado en CI. `apidog login` almacena el token en la máquina que lo ejecuta. Un nuevo ejecutor de CI no tiene ninguno, así que ejecuta `login --with-token` en el mismo trabajo antes de cualquier comando, y guarda el token en un secreto.

Un `$ref` que no apunta a ningún sitio. Cuando un endpoint referencia un modelo de datos con `#/definitions/{schemaId}`, ese esquema debe existir primero. Crea los esquemas antes que los endpoints que los usan.

Preguntas frecuentes

¿Qué agentes de IA pueden usar la CLI de Apidog? Cualquier agente que pueda ejecutar comandos de shell: Claude Code, Cursor, Codex y agentes de codificación similares. La CLI es agnóstica a los agentes; solo necesita comandos correctos y cargas útiles válidas.

¿Necesito un plan de pago? No. Apidog no es de código abierto, pero el nivel gratuito más `apidog-cli` cubre el flujo de creación y publicación descrito aquí.

¿Puede el agente sobrescribir documentos existentes por accidente? `create` añade nuevos recursos. La modificación de los existentes utiliza `update`, que se comporta de manera diferente y necesita sus propias salvaguardias; esto se cubre en la guía complementaria sobre cómo actualizar tu especificación de API.

¿En qué se diferencia esto de un generador de documentación de IA? Las herramientas genéricas de documentación de IA producen texto a partir de tu código. Esto produce documentación *estructurada* dentro de tu plataforma API (endpoints, esquemas, guías y un sitio publicado) a partir de una única fuente viva que no puede desfasarse de lo que edita tu equipo.

En resumen

Un agente que puede ejecutar la CLI de Apidog puede encargarse de la parte de la documentación que la gente siempre pospone: crea los endpoints, escribe las guías a su alrededor y publica el sitio. Todo a partir de una solicitud en lenguaje natural, con la validación de esquemas protegiendo cada escritura. Tu rol pasa de escribir la documentación a revisar un diff.

La única regla que lo hace fiable es el ritual de escritura: obtener el esquema, validar y luego crear. Dale a tu agente ese bucle, el bloque de reglas de cinco líneas de arriba y un ID de proyecto, y la documentación dejará de ser una tarea tediosa que se queda atrás del código. Descarga Apidog para obtener la CLI, o lee la guía completa de la CLI de Apidog para la referencia completa de comandos.