Tienes un archivo OpenAPI y quieres documentación a partir de él. No quieres levantar un servicio, iniciar sesión en un portal, o añadir un paso de compilación que arrastre la mitad de npm. Quieres un solo comando que lea la especificación y te entregue un archivo Markdown o una única página HTML que puedas alojar en cualquier lugar.
Para eso es esta lista. Cada herramienta aquí es pequeña: un solo binario, una línea de comando npx, o un paquete que instalas una vez y olvidas. Se inician rápido, necesitan poca o ninguna configuración, y hacen el trabajo de documentación sin arrastrar una plataforma completa detrás. Algunas emiten Markdown que puedes insertar en un sitio de documentación existente. Otras emiten un archivo HTML independiente. Todas ellas se ejecutan en CI y en una terminal, que es el objetivo.
Si quieres el campo más amplio de plataformas de documentación, el resumen de las mejores herramientas de documentación de API REST cubre el extremo más pesado en GUI. Esta pieza es el corte de baja huella y prioriza la terminal. Para la referencia oficial sobre lo que lee un generador de documentación, la Especificación OpenAPI es la fuente de verdad que todas las herramientas a continuación analizan.
¿Qué hace que una herramienta CLI sea "ligera" para la documentación de API?
Ligera no significa con poca potencia. Se trata de huella y fricción. Cuatro cosas lo deciden.
Tamaño de instalación y dependencias. Un binario o un paquete npm es mejor que un framework. Si generar una página de documentación significa instalar un tiempo de ejecución de lenguaje más un empacador más un sistema de plugins, eso no es ligero, sin importar cómo se vea la salida.
Inicio y configuración. Las mejores de estas leen tu especificación y producen una salida sin configuración. Apuntas el comando a openapi.yaml y obtienes un archivo. Cualquier cosa que necesite un archivo de configuración antes de ejecutarse pierde puntos aquí.
Salida de propósito único. Cada herramienta a continuación hace una cosa: especificación de entrada, documentación de salida. Markdown o HTML, nada más añadido. Eso es lo que las mantiene rápidas y predecibles en una cadena de producción.
Se ejecuta en cualquier lugar. Sin GUI, sin inicio de sesión para las herramientas abiertas, sin servidor que mantener vivo. Funciona en tu portátil y funciona de la misma manera en un trabajo de CI. Para un conjunto más amplio de opciones gratuitas, la lista de herramientas gratuitas de documentación de API tiene las plataformas; esta es la parte CLI de eso.
Ahora las herramientas, las más pequeñas primero.
Widdershins
Widdershins es tan pequeña como se puede. Es un único paquete npm que convierte un archivo OpenAPI 3, Swagger 2 o AsyncAPI en Markdown. Ese es todo su trabajo. No renderiza un sitio ni ejecuta un servidor; te entrega un archivo .md y se aparta.
npm install -g widdershins
widdershins openapi.yaml -o api-docs.md
El Markdown que produce es compatible con Slate, lo cual es importante si planeas introducirlo en un sitio estático más tarde. Banderas útiles: --omitHeader elimina el front-matter YAML, y --language_tabs controla qué lenguajes de ejemplo de código se muestran.
Lo mejor para: obtener contenido de especificación en Markdown que puedes enviar, diferenciar e insertar en cualquier sistema de documentación. Límites honestos: Markdown es todo lo que obtienes. No hay estilo, no hay panel interactivo de "probar", y no hay salida alojada. Widdershins es un convertidor, no un renderizador, así que lo emparejas con algo que convierte Markdown en un sitio.
OpenAPI Generator (generadores de documentación)
OpenAPI Generator es más conocido por los SDK de cliente, pero también incluye generadores de documentación, y son útiles cuando una especificación es todo lo que tienes. El generador markdown escribe una carpeta de Markdown; el generador html2 escribe una sola página HTML autocontenida. Puedes ejecutarlo a través del envoltorio npm sin instalar Java tú mismo.
npm install -g @openapitools/openapi-generator-cli
openapi-generator-cli generate -g markdown -i openapi.yaml -o docs/
openapi-generator-cli generate -g html2 -i openapi.yaml -o docs-html/
El envoltorio npm aún descarga un jar respaldado por JDK bajo el capó, por lo que es más pesado que Widdershins en la primera ejecución. Después de eso, es una generación con un solo comando.
Lo mejor para: reutilizar una herramienta que quizás ya uses para SDKs y también para emitir documentación, con la opción entre Markdown y HTML independiente. Límites honestos: la salida es simple y basada en plantillas, y la primera invocación descarga un jar, por lo que no es verdaderamente de un solo binario. Si solo necesitas documentación y nada más, existen opciones más ligeras.
Redocly CLI (build-docs)
Si quieres una página HTML autónoma y de buen aspecto a partir de un solo comando, Redocly CLI es el camino más corto. El comando build-docs empaqueta tu especificación en un único archivo HTML autocontenido basado en Redoc. Sin servidor, sin construcción de alojamiento separada; obtienes un archivo que puedes abrir, enviar por correo electrónico o colocar en cualquier host estático.
npx @redocly/cli build-docs openapi.yaml
Por defecto, escribe redoc-static.html. Cambia el nombre con --output:
npx @redocly/cli build-docs openapi.yaml --output api.html
Debido a que se ejecuta a través de npx, ni siquiera tienes que instalarlo globalmente para probarlo. Lo mejor para: una referencia pulida de una sola página con un solo comando, con un tema limpio por defecto y sin necesidad de gestionar el alojamiento. Límites honestos: la salida es un único archivo HTML, por lo que es una página de referencia en lugar de un portal de documentación de varias páginas, y los temas y vistas previas más ricos se encuentran en los niveles de pago de Redocly. Si lo estás comparando con renderizadores similares, las comparaciones de alternativas a Redocly y alternativas a Scalar exponen las ventajas y desventajas.
Slate
Slate es la excepción aquí: no es un convertidor de especificación a documentación, es un generador de sitios estáticos para documentación de API escrita a mano. Escribes Markdown, y Slate construye el clásico diseño de documentación de tres columnas (navegación, contenido y ejemplos de código lado a lado) en un sitio estático autocontenido. Está impulsado por Middleman, por lo que necesita Ruby.
# después de clonar el repositorio de slate e instalar las dependencias
bundle exec middleman build
Esto escribe un sitio estático completo en una carpeta build/ que puedes alojar en cualquier lugar. Aquí es donde Widdershins cobra sentido: genera Markdown a partir de tu especificación, luego deja que Slate lo renderice, y obtendrás contenido impulsado por la especificación en el diseño de Slate.
Lo mejor para: documentación de API curada a mano, con narrativa, donde quieres control editorial sobre la estructura y la prosa. Límites honestos: es la opción más pesada de esta lista porque necesita una cadena de herramientas de Ruby, y no lee OpenAPI por sí misma; le proporcionas Markdown. Si tu documentación se genera directamente a partir de una especificación y rara vez se edita a mano, un convertidor solo es más ligero.
Apidog CLI (export + doc)
Las herramientas abiertas anteriores cubren cada una una parte: convertir, renderizar o alojar. Si tu API ya vive en un proyecto en lugar de en un solo archivo YAML, unirlas es la fricción. Ahí es donde encaja el binario apidog-cli. Es el compañero de línea de comandos de Apidog, y una exportación convierte un proyecto en Markdown o HTML sin una cadena de compilación.
Instálalo desde npm y autentícate con un token:
npm install -g apidog-cli
apidog login --with-token <TU_TOKEN>
Luego exporta la documentación del proyecto a Markdown o HTML en un solo comando:
apidog export --project <projectId> --format markdown --output ./api-docs.md
apidog export --project <projectId> --format html --output ./api-docs.html
La CLI también gestiona los recursos de documentación directamente. apidog doc maneja los documentos Markdown del proyecto, y apidog docs-site gestiona los sitios de documentación publicados, para que puedas listar, crear y actualizar documentos desde un script o trabajo de CI:
apidog doc list --project <projectId>
apidog docs-site list --project <projectId>
La salida es JSON estructurado, lo que facilita su paso a otros pasos o a un agente. Para la superficie completa de comandos, la guía completa de Apidog CLI detalla la autenticación, los proyectos y cada grupo de comandos.
Aquí está el encuadre honesto. Apidog no es de código abierto, y no es un binario de propósito único; es una plataforma freemium, y la CLI se comunica con un proyecto alojado. Tampoco revisa tu OpenAPI ni impone una guía de estilo; Redocly y Spectral hacen eso. Lo que te da la CLI es una ruta integrada desde un proyecto API mantenido a Markdown o HTML compartible, en lugar de encadenar un convertidor, un renderizador y un host a mano. Si quieres específicamente la ruta de exportación a markdown, la pieza del generador de documentación de API con exportación a Markdown profundiza en ese flujo de trabajo.
Cómo elegir
Haz coincidir la herramienta con la forma de tu entrada y la salida que necesitas.
| Herramienta | Mejor para | Instalación | ¿Código abierto? | Salida |
|---|---|---|---|---|
| Widdershins | Especificación a Markdown, rápido | npm i -g widdershins |
Sí (MIT) | Markdown |
| OpenAPI Generator | Documentación junto a SDKs | npm i -g @openapitools/openapi-generator-cli |
Sí (Apache 2.0) | Markdown o HTML |
| Redocly CLI | Una página HTML pulida | npx @redocly/cli |
Sí (MIT, núcleo abierto) | HTML autónomo |
| Slate | Sitio de documentación curado a mano | Ruby + Bundler | Sí (Apache 2.0) | Sitio estático |
| Apidog CLI | Exportar desde un proyecto en vivo | npm i -g apidog-cli |
No (nivel gratuito) | Markdown o HTML |
La versión corta: si tienes una especificación básica y quieres Markdown para enviar, usa Widdershins. Si quieres una página HTML compartible, redocly build-docs es lo más rápido. Si estás escribiendo documentación a mano y quieres un diseño adecuado, Slate. Y si tu API ya vive en un proyecto y quieres exportación más gestión de documentos en una sola CLI, Apidog. Para una visión general gratuita, el resumen de herramientas gratuitas de documentación de API lo resume todo.
Conclusión
Las herramientas de documentación ligeras se resumen en una regla: elige la cosa más pequeña que produzca la salida que necesitas. Widdershins y redocly build-docs cubren la mayoría de los casos de especificación a documentación en un solo comando. OpenAPI Generator vale la pena cuando ya estás generando SDKs. Slate justifica su mayor huella solo cuando estás escribiendo documentación a mano. Y cuando tu API vive en un proyecto real en lugar de un archivo suelto, la exportación de apidog-cli te proporciona Markdown o HTML sin necesidad de una cadena de producción.
Si ese último caso es el tuyo, descarga Apidog y prueba apidog export con un proyecto; se integra limpiamente en un trabajo de CI para que tu documentación se reconstruya cada vez que la API cambie.