La documentación de la API queda obsoleta en el momento en que alguien edita una especificación y olvida regenerar la referencia. La solución es dejar de tratar la documentación como un paso manual. Si puedes producir documentos con un solo comando, puedes integrar ese comando en CI y dejar que se ejecute en cada fusión.
Hacerlo desde la terminal tiene otras ventajas. Los comandos son programables, dejan una diferencia que puedes revisar, y un agente de IA o un ejecutor de CI puede activarlos sin que nadie abra un navegador. Sin clics en la GUI, sin "¿recordaste presionar exportar?".
Esta guía recorre primero la ruta general abierta: convertir un archivo OpenAPI en una referencia HTML independiente o un archivo Markdown con un solo comando. Luego profundiza en la ruta de la CLI de Apidog, que extrae tu documentación directamente de un proyecto en vivo para que la fuente de verdad y la salida se mantengan sincronizadas. Si deseas más información sobre el panorama, consulta nuestro resumen de las mejores herramientas de documentación de API REST y las herramientas gratuitas de documentación de API que vale la pena conocer.
Necesitas una cosa para seguir: un archivo OpenAPI 3.x. La mayoría de estos comandos aceptan openapi.yaml o openapi.json indistintamente.
Construye una referencia HTML con Redocly CLI
Redocly CLI es la forma más rápida de convertir una descripción OpenAPI en una página HTML pulida y autocontenida. Renderiza tu especificación con Redoc y escribe todo (estilos, script y contenido) en un solo archivo que puedes alojar en cualquier lugar o enviar por correo electrónico a un compañero de equipo.
Instálalo globalmente, o salta la instalación y ejecútalo con npx:
npm install @redocly/cli -g
Luego, apunta a tu especificación:
redocly build-docs openapi.yaml
Por defecto, esto escribe redoc-static.html en el directorio actual. Abre ese archivo en un navegador y tendrás una referencia completa de API de tres paneles. Para controlar el nombre o la ruta del archivo, usa --output:
redocly build-docs openapi.yaml --output docs/index.html
Ese es todo el flujo de trabajo. Un archivo de entrada, un comando, un artefacto HTML. Funciona con descripciones Swagger 2.0 y OpenAPI 3.0/3.1, por lo que la mayoría de las especificaciones existentes se renderizan sin cambios. La desventaja es el alcance: build-docs te da una página de referencia y nada más. Las guías de formato largo, tutoriales y páginas de inicio de sesión quedan fuera de ella.
Genera Markdown con Widdershins
A veces no quieres HTML. Quieres Markdown que puedas colocar en un sitio de documentación, un generador de sitios estáticos o la carpeta docs/ de un repositorio. Widdershins convierte una definición OpenAPI, Swagger o AsyncAPI en Markdown compatible con Slate.
Instálalo desde npm:
npm install -g widdershins
Luego convierte tu especificación, enviando la salida a un archivo con -o:
widdershins openapi.yaml -o api.md
Si omites -o, Widdershins imprime en la salida estándar, lo cual es útil si quieres canalizarlo a otro lugar. También puedes alternar las pestañas de idioma para los ejemplos de código:
widdershins openapi.yaml --language_tabs 'shell:cURL' 'python:Python' -o api.md
Widdershins es una buena opción cuando tu pipeline de documentación se basa primero en Markdown. Si estás construyendo un flujo de exportación de Markdown más amplio, nuestra guía sobre el uso de un generador de documentos API con exportación de Markdown cubre las herramientas circundantes. El inconveniente tanto con Redocly como con Widdershins es el mismo: leen un archivo estático. Si tu definición de API reside en una herramienta de diseño y se desvía del archivo en el disco, estás documentando la especificación de ayer.
Documenta desde un proyecto en vivo con la CLI de Apidog
Aquí es donde la ruta integrada da sus frutos. Apidog no es de código abierto, pero su nivel gratuito más apidog-cli te ofrece una alternativa a la unión de herramientas separadas: tus puntos finales, esquemas y documentos escritos viven todos en un solo proyecto, y la CLI exporta desde ese proyecto a demanda. Nada se desvía, porque la exportación lee la misma fuente que edita tu equipo.
Instala la CLI desde npm:
npm install -g apidog-cli
Si estás configurando por primera vez, nuestra guía de instalación de Apidog CLI cubre las versiones de Node y la configuración de PATH. Luego autentícate una vez con un token de acceso personal:
apidog login --with-token <TOKEN>
El token se almacena, por lo que no lo pasas en cada llamada. A partir de aquí, todo se ejecuta contra un ID de proyecto. Agrega --help a cualquier comando para ver sus banderas exactas antes de ejecutarlo.
Importa una especificación al proyecto
Si tu API ya existe en un archivo OpenAPI, impórtala a un proyecto para que la CLI tenga algo que exportar:
apidog import --help
apidog import --project <projectId> --format openapi --file ./openapi.json
apidog import acepta formatos OpenAPI 3.x, Swagger 2.0, Postman y Apidog, por lo que puedes importar una colección de Postman o una exportación existente de Apidog de la misma manera. Una vez que la especificación se importa, se convierte en la fuente viva de la que todo lo demás lee.
Exporta documentos legibles por humanos
Este es el comando principal. apidog export escribe OpenAPI, HTML, Markdown o Postman, así que ejecuta --help primero para ver el formato exacto y las banderas de salida que incluye tu versión, luego exporta la documentación del proyecto a Markdown:
apidog export --help
apidog export --project <projectId> --format markdown --output ./api-docs.md
Abre api-docs.md y tendrás una referencia completa generada a partir del estado actual del proyecto. ¿Quieres HTML en su lugar? Cambia una bandera:
apidog export --project <projectId> --format html --output ./api-docs.html
También puedes exportar de nuevo a OpenAPI cuando quieras una especificación portable para entregar más adelante:
apidog export --project <projectId> --format openapi --output ./openapi.json
Si tu proyecto contiene varios servicios y solo quieres documentar una parte, la exportación permite reducir el alcance. Consulta apidog export --help para conocer las banderas de alcance e ID en tu versión, ya que un solo proyecto puede enviar un archivo de documento por servicio de esa manera.
Gestiona las guías escritas, no solo la referencia
Una referencia generada a partir de tu esquema es solo la mitad de la historia. La otra mitad es la prosa: guías de inicio, tutoriales de autenticación, notas de migración. En Apidog, estas viven en el árbol de documentos del proyecto como documentos Markdown, y la CLI las gestiona con el grupo de comandos doc.
Comienza leyendo la ayuda del grupo para que trabajes con las banderas exactas que incluye tu versión:
apidog doc --help
apidog doc list --project <projectId>
A partir de ahí, el flujo tiene la misma forma que todo lo demás en la CLI: ejecuta el comando en tu proyecto, lee el resultado JSON y sigue los agentHints.nextSteps que te devuelve. Cuando un comando requiere una carga útil JSON, la CLI puede imprimir el esquema que espera y validar tu archivo contra él antes de que envíes nada, para que detectes un campo faltante en tu máquina en lugar de en una llamada fallida. Consulta apidog cli-schema --help para el subcomando de validación exacto.
Publica un sitio de documentación
Cuando la referencia y las guías estén listas, también puedes gestionar la documentación publicada desde la terminal. Dos comandos lo cubren, y leer su ayuda primero evita una bandera adivinada:
apidog docs-site --help
apidog shared-doc --help
Una nota sobre la nomenclatura que confunde a la gente: un doc es un documento Markdown dentro del árbol de la API del proyecto, docs-site gestiona el sitio de documentación pública alojado, y shared-doc gestiona los enlaces de documentación compartibles. Opta por docs-site cuando quieras un sitio público definido desde la terminal en lugar de hacer clic en una interfaz de usuario, y shared-doc cuando solo quieras un enlace para entregar a un socio. La ventaja es que la publicación se convierte en un paso programado: cuando tu especificación cambia, reimportas o editas el proyecto, luego ejecutas el comando de publicación nuevamente, y la documentación alojada refleja la actualización.
Conéctalo a CI
La razón para ejecutar cualquiera de estos desde la CLI es la repetibilidad. Una vez que los comandos funcionan localmente, funcionan en una pipeline. Un paso mínimo de GitHub Actions que regenera y confirma tu referencia de Markdown en cada push se ve así:
- 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
Reemplaza con redocly build-docs o widdershins y la forma es idéntica. Los documentos dejan de ser una tarea que alguien recuerda hacer y se convierten en un artefacto de compilación que se regenera a sí mismo. Para la referencia completa de comandos, consulta la guía completa de Apidog CLI.
Inconvenientes comunes
ID de proyecto incorrecto o faltante. Cada llamada de Apidog a export, doc y docs-site necesita --project <projectId>. El ID se encuentra en la configuración del proyecto, no en el nombre del proyecto legible por humanos. Si un comando da un error quejándose del proyecto, esa es casi siempre la causa.
Token no configurado en CI. apidog login almacena el token en la máquina que lo ejecuta. En un runner de CI fresco no hay token almacenado, por lo que debes ejecutar login --with-token en el mismo trabajo antes de cualquier exportación. Almacena el token como un secreto, nunca en el archivo de flujo de trabajo.
Exportaciones de archivos obsoletos. Redocly y Widdershins leen cualquier archivo que les entregues. Si tu openapi.yaml está desactualizado, también lo están tus documentos. Este es exactamente el desvío que la ruta de Apidog evita al exportar desde el proyecto en vivo en lugar de un archivo en disco.
Adivinar las banderas en lugar de leer --help. Las banderas exactas para export, doc, docs-site y shared-doc pueden variar según la versión de la CLI. Ejecuta apidog <comando> --help y trabaja con lo que imprime en lugar de una bandera que recuerdes a medias. Lleva dos segundos y evita una compilación fallida.
En resumen
Documentar una API desde la terminal se reduce a elegir la salida correcta. Opta por Redocly CLI cuando quieras una referencia HTML independiente, Widdershins cuando quieras Markdown para un sitio de documentación, y la CLI de Apidog cuando quieras referencia más guías escritas más un sitio publicado, todo exportado desde una única fuente viva. Esta última opción es la que mantiene tus documentos honestos, porque la exportación y lo que tu equipo edita son el mismo proyecto.
Cada comando aquí es programable, lo que significa que cada uno de ellos pertenece a CI. Configúralo una vez y tu documentación se regenerará con cada cambio. Descarga Apidog para obtener la CLI y prueba el flujo de exportación con tu propio proyecto, o lee más sobre cómo Apidog encaja en un flujo de trabajo API-first.