Cuando eliges una herramienta para generar la documentación de tu API, la licencia es parte de la decisión. Un generador de código abierto significa que puedes leer el código, autoalojar el resultado, bifurcarlo si se estanca y nunca alcanzar un límite de asientos o un muro de pago por una función que ya implementaste. Para un trabajo que se ejecuta en cada compilación de CI, eso importa tanto como la calidad del resultado.
Esta lista es la selección de código abierto de herramientas de documentación de API que se ejecutan desde la línea de comandos. Cada herramienta aquí es de código fuente disponible bajo una licencia real, MIT o Apache 2.0, alojada en GitHub, y de uso gratuito sin necesidad de cuenta. La apuntas a un archivo OpenAPI o Swagger y te entrega Markdown, una página HTML estática o un sitio de documentación completo que posees y alojas tú mismo.
Marcaré la licencia exacta y la historia del autoalojamiento para cada una, porque esa es la razón principal por la que estás leyendo un resumen de código abierto en lugar de uno general. Si quieres el campo más amplio, el resumen de las mejores herramientas de documentación de API REST también cubre las plataformas GUI. La Especificación OpenAPI es el formato que leen todas las herramientas a continuación, por lo que una especificación válida es tu punto de partida.
Una nota honesta de antemano. Apidog aparece cerca del final, y no es una entrada de código abierto; es una plataforma freemium comercial. La he incluido solo como una nota al margen etiquetada para el caso en que las herramientas abiertas dejen una brecha, y seré explícito sobre esa línea.
Qué hace que una herramienta de documentación CLI sea “de código abierto”
El código abierto no es solo «gratis para descargar». Para las herramientas de documentación que conectarás a una compilación, tres cosas deciden si una herramienta es realmente tuya.
Una licencia real. MIT o Apache 2.0 significa que puedes usar, modificar y redistribuir la herramienta comercialmente sin preguntar. Ambas están aprobadas por la OSI. Apache 2.0 añade una concesión explícita de patente, lo que algunos equipos legales prefieren. Todas las herramientas a continuación llevan una de las dos.
Salida autoalojable. El objetivo de la documentación abierta es que nada dependa de los servidores de un proveedor. Estas herramientas escriben archivos estáticos: Markdown que tú subes, una única página HTML o una carpeta de HTML/CSS/JS. Lo alojas en GitHub Pages, S3 o un simple servidor Nginx, y sigue funcionando independientemente de si el proyecto detrás de la herramienta lo hace o no.
Mantenimiento y comunidad. El código fuente disponible solo ayuda si el código está vivo. Las estrellas, los commits recientes y los problemas abiertos te dicen si una bifurcación sería viable si alguna vez la necesitaras. Un par de herramientas aquí están archivadas pero aún funcionan; lo mencionaré.
Para el ángulo sin costo en opciones tanto abiertas como freemium, la lista de herramientas gratuitas de documentación de API es la pieza complementaria. Ahora las herramientas.
Redocly CLI
Redocly CLI es la forma más rápida de convertir una especificación en una referencia HTML pulida y autocontenida. Tiene licencia MIT y es de núcleo abierto: la CLI y el motor de renderizado Redoc subyacente son de código abierto en GitHub, mientras que algunas características de portal alojado residen en el producto de pago de Redocly. El comando build-docs está completamente en la parte abierta.
npx @redocly/cli build-docs openapi.yaml -o api-docs.html
Eso escribe un archivo HTML construido sobre Redoc. Ábrelo localmente, suéltalo en cualquier host estático o adjúntalo a una versión. Nada llama a casa, y puedes ejecutarlo sin conexión una vez que el paquete esté en caché.
Lo mejor en: una referencia de API limpia de una sola página con un solo comando, con licencia MIT y autoalojada. Límites honestos: la salida es una sola página, por lo que es una referencia en lugar de un portal multipágina, y la temática más rica se encuentra en el nivel de pago. Si estás comparando los motores de renderizado, la comparación de alternativas a Redocly expone dónde cae la línea abierta.
Widdershins
Widdershins es un conversor puro bajo la licencia MIT. Lee OpenAPI 3, Swagger 2 o AsyncAPI y emite Markdown; ese es todo su trabajo. Debido a que la salida es Markdown simple, lo posees completamente: súbelo, compáralo en una solicitud de extracción o aliméntalo a cualquier sitio estático que ya tengas en funcionamiento.
npm install -g widdershins
widdershins openapi.yaml -o api-docs.md
El Markdown que escribe es compatible con Slate, lo que lo combina perfectamente con los generadores de sitios más adelante en esta lista. Banderas útiles: --omitHeader elimina el 'front-matter', y --language_tabs selecciona los lenguajes de los ejemplos de código.
Lo mejor en: obtener contenido de la especificación en Markdown controlable por versiones sin dependencia. Límites honestos: Markdown es todo lo que obtienes. No hay estilo ni sitio renderizado, por lo que Widdershins es la mitad de una cadena de producción; otra cosa convierte el Markdown en páginas.
OpenAPI Generator
OpenAPI Generator tiene licencia Apache 2.0 y es gestionado por la comunidad, bifurcado de Swagger Codegen en 2018. Es más conocido por los SDK de cliente, pero también incluye generadores de documentación: el generador markdown escribe una carpeta de Markdown, y html2 escribe una única página HTML autocontenida.
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/
La licencia Apache 2.0 y su concesión de patente facilitan la aprobación para equipos legales cautelosos, y el proyecto es uno de los más activamente mantenidos en este ámbito.
Lo mejor en: reutilizar una herramienta para SDKs y documentación, bajo una licencia permisiva con fuerte apoyo de la comunidad. Límites honestos: el 'wrapper' de npm aún descarga un jar de Java en la primera ejecución, por lo que no es un único binario, y la salida con plantilla es simple. Si solo necesitas documentación, existen convertidores más ligeros.
Swagger Codegen
Swagger Codegen es el generador original basado en plantillas del equipo de Swagger, con licencia Apache 2.0. Es anterior a la bifurcación de OpenAPI Generator y sigue siendo mantenido por SmartBear. Para la documentación ofrece dos caminos: html para una referencia estática de una sola página y dynamic-html para un pequeño sitio interactivo.
npm install -g swagger-codegen-cli
swagger-codegen-cli generate -i openapi.yaml -l html -o docs/
Los dos proyectos comparten ADN y muchas opciones, por lo que si tu equipo ya se estandarizó en la cadena de herramientas de Swagger, esto te mantiene dentro de ella.
Lo mejor en: equipos ya invertidos en el ecosistema Swagger que desean documentación de la misma herramienta Apache 2.0 que genera sus stubs. Límites honestos: está respaldado por Java como OpenAPI Generator, y el desarrollo avanza más lento que la bifurcación de la comunidad. Para la mayoría de las nuevas configuraciones, OpenAPI Generator es la opción más activa; Swagger Codegen gana en continuidad.
Docusaurus con el plugin OpenAPI
Si una sola página HTML no es suficiente y deseas un sitio de documentación real y versionado, Docusaurus es el pilar de código abierto. Tiene licencia MIT, fue creado por Meta y es uno de los generadores de sitios estáticos más utilizados en la web. Por sí solo, renderiza Markdown y MDX; el plugin docusaurus-openapi-docs, también MIT y mantenido por Palo Alto Networks, añade la generación de especificación a documentación.
npx create-docusaurus@latest my-docs classic
npm install docusaurus-plugin-openapi-docs docusaurus-theme-openapi-docs
npm run docusaurus gen-api-docs all
Después de configurar el plugin con la ruta de tu especificación, gen-api-docs convierte el archivo OpenAPI en páginas MDX que se renderizan dentro del sitio de Docusaurus, completas con un panel de “pruébalo” y navegación en la barra lateral.
Lo mejor en: un portal de documentación completo y autoalojado con versionado, búsqueda y guías escritas a mano junto con la referencia generada. Límites honestos: es la configuración más pesada aquí. Estás montando un sitio React y un paso de compilación, por lo que es excesivo si todo lo que necesitas es una página de referencia. Para eso, Redocly CLI es el camino más corto.
Slate
Slate es el diseño clásico de documentación de API de tres columnas: navegación a la izquierda, texto en el medio, ejemplos de código a la derecha, todo renderizado como un sitio estático. Tiene licencia Apache 2.0 y funciona con Middleman, por lo que necesita una cadena de herramientas de Ruby. A diferencia de los convertidores anteriores, Slate no lee OpenAPI directamente; tú escribes Markdown y Slate lo renderiza.
# after cloning your Slate fork and running bundle install
bundle exec middleman build
Eso escribe un sitio estático completo en una carpeta build/ que puedes alojar en cualquier lugar. Aquí es donde Widdershins vale la pena: convierte tu especificación a Markdown y luego deja que Slate lo renderice en ese diseño reconocible.
Lo mejor en: documentación narrativa, curada a mano, donde deseas control editorial sobre la estructura y la prosa, en un sitio estático completamente autoalojado. Límites honestos: el repositorio original está archivado (el mantenedor se retiró), aunque todavía se compila y las bifurcaciones están activas, y la dependencia de Ruby es más pesada que una línea npx. Si tu documentación se regenera directamente desde una especificación, un convertidor es más ligero.
Apidog CLI (nota honesta al margen, no es una entrada de código abierto)
Todas las herramientas anteriores son de código abierto, y cada una cubre un segmento: convertir, renderizar o alojar un archivo estático. La brecha que dejan es un proyecto en vivo. Si tu API no es un archivo YAML solitario, sino un proyecto mantenido con endpoints, esquemas y ejemplos, terminas encadenando un convertidor, un renderizador y un host a mano y manteniendo los tres sincronizados.
Esa es la brecha que llena el binario apidog-cli. Para ser directos sobre la licencia: Apidog no es de código abierto. Es una plataforma freemium comercial con un nivel gratuito, y la CLI se comunica con un proyecto alojado en lugar de una especificación local. La incluyo aquí solo para que la comparación sea honesta sobre lo que las herramientas abiertas cubren y no cubren, no como una opción de código abierto.
npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>
apidog export --project <projectId> --format markdown --output ./api-docs.md
apidog export --project <projectId> --format html --output ./api-docs.html
Una exportación convierte el proyecto en Markdown o HTML sin una cadena de compilación, y apidog doc y apidog docs-site gestionan los recursos de documentación desde un script. La salida es JSON estructurado, por lo que se integra limpiamente en CI o en un agente. La guía completa de Apidog CLI detalla la autenticación y cada grupo de comandos. Si el flujo de trabajo de exportación a Markdown es lo que buscas, la pieza sobre el generador de documentación de API con exportación a Markdown profundiza más.
Dónde está la diferencia: las herramientas abiertas te dan código que posees, archivos que autoalojas y ninguna dependencia de proveedor. Apidog te ofrece una ruta integrada desde un proyecto mantenido hasta documentos compartibles, a costa de ser un producto freemium alojado. Elige en función de si tu fuente de verdad es una especificación estática o un proyecto en vivo.
Cómo elegir
Haz coincidir la licencia y la salida con lo que tu equipo necesita poseer.
| Herramienta | Lo mejor para | Instalación | ¿Código abierto? | Salida |
|---|---|---|---|---|
| Redocly CLI | Una página HTML pulida | npx @redocly/cli |
Sí (MIT, núcleo abierto) | HTML independiente |
| Widdershins | Especificación a Markdown que tú subes | npm i -g widdershins |
Sí (MIT) | Markdown |
| OpenAPI Generator | Docs más SDKs, una herramienta | npm i -g @openapitools/openapi-generator-cli |
Sí (Apache 2.0) | Markdown o HTML |
| Swagger Codegen | Equipos estandarizados en Swagger | npm i -g swagger-codegen-cli |
Sí (Apache 2.0) | HTML |
| Docusaurus + OpenAPI plugin | Sitio de documentación completo autoalojado | npx create-docusaurus |
Sí (MIT) | Sitio estático |
| Slate | Docs de tres columnas curadas 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 (freemium) | Markdown o HTML |
La versión corta: para una especificación básica y una referencia HTML compartible, usa Redocly CLI. Para Markdown que controlas por versiones, Widdershins. Si ya estás generando SDKs, OpenAPI Generator también hace documentación, y Swagger Codegen te cubre si estás estandarizado en Swagger. Cuando quieres un portal real con versionado y guías, Docusaurus más el plugin OpenAPI es el pilar de código abierto, y Slate es la elección para documentos escritos a mano y controlados editorialmente. Cada una de estas opciones tiene el código fuente disponible y es autoalojable, por lo que nada de lo que envíes depende de que un proveedor siga en el negocio. Para una visión más amplia sin costo, el resumen de herramientas gratuitas de documentación de API reúne opciones abiertas y freemium.
Conclusión
Elegir una CLI de documentación de código abierto se reduce a la licencia, la salida y dónde reside tu documentación. MIT y Apache 2.0 te permiten usar, modificar y autoalojar sin costo por asiento, así que elige la herramienta más pequeña que produzca la salida que necesitas: Redocly CLI para una página, Widdershins para Markdown, OpenAPI Generator o Swagger Codegen para documentación junto a tus SDKs, Docusaurus para un portal, Slate para páginas curadas a mano.
Si tu API reside en un proyecto mantenido en lugar de un archivo suelto, y prefieres exportar la documentación en lugar de encadenar tres herramientas, Descarga Apidog y prueba apidog export en un proyecto. Se integra en un trabajo de CI para que tu documentación se reconstruya cada vez que la API cambie, solo ten claro que es una plataforma freemium, no un binario de código abierto.