Cómo migrar de Redocly a Apidog sin perder tu flujo de trabajo Docs-as-Code

Si gestionas tu portal para desarrolladores con Redocly, ya trabajas como la mayoría de los equipos de API quieren: openapi.yaml vive en Git, las guías están en Markdown y un push actualiza la documentación. El miedo al cambiar de herramienta es perder ese ciclo y acabar editando la documentación a mano en una interfaz web.

No tienes por qué hacerlo. El modo Spec-first de Apidog mantiene tu spec y tu Markdown en el mismo repositorio, sincroniza en cada push mediante un webhook y publica un portal con guías y una referencia de API en una sola barra lateral. Esta guía recorre la migración, incluida la única parte que no se transfiere automáticamente: el contenido extenso que muchos usuarios de Redocly guardan dentro de info.description y tags[].description.

Si todavía estás comparando herramientas, empieza por Apidog vs. Redocly o por la lista más amplia de alternativas a Redocly. Este artículo asume que ya has elegido Apidog y quieres hacer el cambio sin romper tu flujo de trabajo.

Qué se transfiere y qué no

Probamos esta migración con una spec de producción real: OpenAPI 3.0.3, 62 operaciones repartidas en 13 tags, con contenido de primeros pasos, autenticación e integración escrito en los campos description de la spec. Esto es lo que ocurrió al importar.

La referencia de la API se transfiere sin cambios. El vacío está en el contenido narrativo.

Por qué tus campos description no se renderizan igual

Redoc, el renderizador que hay detrás de la documentación de referencia de Redocly, trata info.description como un mini documento. Cada encabezado Markdown que contiene se convierte en una entrada de la barra lateral, así que los equipos suelen escribir ahí todas sus guías de «Primeros pasos» y «Autenticación». Las descripciones de los tags se renderizan como texto de introducción en la parte superior de cada grupo de tags.

Eso es una convención de Redoc, no forma parte de la especificación OpenAPI. La especificación solo define description como una cadena CommonMark. Apidog, como la mayoría de los portales, mantiene las guías como documentos Markdown independientes y reserva la spec para la referencia. Una publicación predeterminada después de la importación muestra únicamente la referencia de la API, sin las guías que escribiste en los campos description.

La solución es un traslado único: saca ese contenido del YAML y llévalo a archivos Markdown junto a él. A partir de ahí, todo sigue funcionando con Git.

La estructura del repositorio de destino

Esta es la estructura que validamos:

your-repo/
├── openapi.yaml              # source of truth for the API reference
└── docs/
    ├── getting-started.md
    ├── authentication.md
    └── embed-integration-guide.md

openapi.yaml controla la referencia de la API. Cada archivo de docs/ se convierte en una página de la barra lateral del portal. Las imágenes a las que hacen referencia esos archivos Markdown pueden vivir en el mismo repositorio y sincronizarse con ellos.

Si usabas el sidebars.yaml de Redocly para ordenar tu navegación, consérvalo como referencia. Establecerás ese mismo orden una vez en la configuración del sitio de documentación de Apidog.

Migración paso a paso

1. Audita qué hay dentro de tus campos description

Antes de mover nada, comprueba cuánto contenido hay en la spec. Con yq:

# How long is the top-level description?
yq '.info.description' openapi.yaml | wc -w

# Which headings does it contain? Each one is a Redoc sidebar entry today.
yq '.info.description' openapi.yaml | grep -E '^#{1,3} '

# Which tags carry a description?
yq '.tags[] | select(.description != null) | .name' openapi.yaml

La lista de encabezados es tu futura lista de archivos en docs/. En nuestra prueba, info.description se dividió en dos archivos Markdown, y las descripciones de los tags se convirtieron en páginas de introducción por carpeta más un archivo Markdown adicional.

2. Divide info.description en archivos Markdown

Copia cada sección de nivel superior a su propio archivo dentro de docs/. Conserva los encabezados, los ejemplos de código y los enlaces. Después, reduce info.description en la spec a un resumen de un párrafo, para que el contenido viva en un solo lugar.

Ojo con dos características específicas de Redoc mientras copias:

• <SecurityDefinitions /> y otros tags similares de Redoc no se renderizan fuera de Redoc. Sustitúyelos por una breve sección escrita que enlace a los esquemas de seguridad de la referencia.
• Los enlaces como #tag/Payments apuntan a anclas de Redoc. Actualízalos a las URL del documento o la carpeta correspondientes de Apidog después de la primera publicación.

3. Conecta el repositorio en el modo Spec-first

Crea un proyecto en el modo Spec-first, conecta tu repositorio (GitHub, GitLab, Azure DevOps o Bitbucket), apúntalo a openapi.yaml y a la carpeta docs/, e instala el webhook. A partir de entonces, un push a la rama monitorizada actualiza el proyecto.

Tras la primera sincronización, el espacio de trabajo Specs muestra tu spec y el resto del repositorio. La pestaña APIs lista las operaciones analizadas de openapi.yaml, Docs contiene tus páginas Markdown y All files refleja el repositorio.

El webhook es lo que mantiene esto como un flujo de trabajo de documentación como código. Sin él, tendrías que lanzar las sincronizaciones a mano. Si quieres recordar por qué importa esto, consulta nuestra guía sobre docs as code.

4. Publica el sitio de documentación y configura la navegación

Publica un sitio de documentación desde el proyecto y organiza la barra lateral. El orden que quieren la mayoría de los usuarios de Redocly, y el que reprodujimos, es:

1. Primeros pasos
2. Autenticación
3. Guías de integración
4. Referencia de la API (las carpetas de endpoints de tus tags)

Las páginas Markdown y las carpetas de API se mezclan libremente en un mismo árbol, así que puedes replicar de cerca tu barra lateral actual de Redocly.

5. Añade tu dominio personalizado

Apunta un CNAME como developers.example.com al sitio de documentación. Los dominios personalizados están disponibles en el plan gratuito.

Deja que tu agente de programación migre las descripciones de los tags con Apidog CLI

Las descripciones de los tags son la parte más tediosa. Trece tags significan trece tareas de copiar y pegar, y tendrás que rehacerlas cada vez que cambie una descripción de tag durante la transición. Dáselo a tu agente de programación.

Apidog CLI da a Claude Code, Codex, Cursor o cualquier agente de terminal acceso JSON estructurado a tu proyecto, incluidas las carpetas de endpoints. Configúralo una vez:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_ACCESS_TOKEN>
npx -y skills add https://apidog.com

La última línea instala la skill de Apidog para que tu agente conozca los comandos sin tener que adivinarlos. La guía de instalación cubre los tokens y los despliegues privados.

Después, dale a tu agente un solo prompt:

Lee openapi.yaml. Para cada tag con una descripción, encuentra la carpeta de endpoints correspondiente en el proyecto de Apidog <PROJECT_ID> y establece la descripción de esa carpeta como la descripción del tag. Valida cada payload con apidog cli-schema validate folder-update antes de escribir. Muéstrame la lista de carpetas que has cambiado.

Esto es lo que ejecuta el agente:

# Find the folder IDs that correspond to your tags
apidog folder list --project <PROJECT_ID> --type endpoint

# Check the payload shape instead of guessing it
apidog cli-schema get folder-update

# For each tag: write {"description": "..."} to a file, validate, then update
apidog cli-schema validate folder-update --file ./payments-folder.json
apidog folder update <FOLDER_ID> --project <PROJECT_ID> --type endpoint \
  --file ./payments-folder.json

El esquema folder-update acepta name, parentId y description, y description es compatible con las carpetas de endpoints y de escenarios de prueba. Para las guías que no pertenecen a un único tag, el agente puede usar apidog doc list y apidog doc create de la misma forma, después de leer apidog cli-schema get doc-create.

Para mostrar la introducción de una carpeta en el sitio publicado, configura Folder Contents Displaying Setting en los ajustes de la carpeta, dentro de Documentation Settings after Publication.

Una advertencia honesta: mostrar las descripciones de los tags como páginas de introducción por categoría funciona, pero se apoya en un camino menos documentado. Pruébalo en dos o tres carpetas de tu propio espacio de trabajo antes de depender de ello para todas. Para más trabajo de spec impulsado por agentes, consulta usar Apidog CLI en Claude Code y dejar que un agente actualice tu spec de API.

Qué queda fuera de Git

Un proyecto Spec-first mantiene tu API y tu Markdown en Git. Algunos ajustes del portal viven en la interfaz de Apidog y no están bajo control de versiones:

Son elementos que se configuran una sola vez. Los tocas cuando añades una nueva sección de nivel superior, no en cada cambio de contenido. Redocly guarda más de esto en redocly.yaml y sidebars.yaml, así que si hoy revisas los cambios de navegación en pull requests, ten previsto que eso pase a la interfaz.

Plan y precios

La configuración descrita aquí cabe en el plan gratuito, incluido el dominio personalizado. El plan gratuito admite hasta 4 miembros del equipo. Los planes de pago añaden cosas como varios sitios de documentación por proyecto y controles de visibilidad personalizados. Consulta los precios de Apidog para conocer los límites actuales.

Redocly vs. Apidog después de la migración

El intercambio es sencillo. Pierdes la navegación definida en YAML. Ganas pruebas, mocking y una CLI amigable para agentes sobre la misma spec de la que salen tus documentos. Para un análisis CLI por CLI, lee Apidog CLI vs Redocly CLI.

FAQ

¿Seguirán funcionando mis URL alojadas en Redocly? No de forma automática. Las rutas de las páginas cambian. Si tu antiguo portal tenía URL de guías con mucho tráfico, añade redirecciones en tu capa de DNS o proxy para las páginas principales después de cambiar el dominio.

¿Tengo que reescribir mi spec de OpenAPI? No. La spec se importa tal cual. Solo mueves el contenido narrativo de info.description y tags[].description a archivos Markdown.

¿Puedo conservar x-tagGroups? Usa carpetas para agrupar en su lugar. Cada tag se convierte en una carpeta, y puedes anidar carpetas para reproducir tus grupos de tags.

¿Cómo se compara esto con migrar desde Stoplight? La forma es similar: spec en Git, Markdown al lado, sincronización por webhook. Consulta cómo migrar de Stoplight a Apidog si usas ambas herramientas.

¿Y si algún paso se comporta de forma distinta en mi espacio de trabajo? Nuestros resultados provienen de un entorno de prueba. Vuelve a ejecutar la importación primero en una rama y compara el portal publicado con el actual antes de cambiar el DNS.

Haz el cambio en una tarde

Una migración de Redocly a Apidog es, sobre todo, un traslado de contenido. Tu spec se importa tal cual. Tus guías salen de los campos description a una carpeta docs/ una sola vez. A partir de ahí, un webhook lo mantiene todo sincronizado. Deja que tu agente se encargue del trabajo repetitivo de las descripciones de tags con Apidog CLI, y dedica tu tiempo a revisar el portal publicado página por página.

Descarga Apidog y conecta tu repositorio al modo Spec-first para empezar la migración.