Si ya has adoptado Bruno, ya conoces su atractivo. Tus colecciones viven como simples archivos .bru en tu repositorio Git, con control de versiones junto al código, sin necesidad de una cuenta en la nube. Es una respuesta limpia y "offline-first" para clientes de API que quieren ser dueños de sus datos.
Pero tarde o temprano, alguien hace una pregunta que Bruno no responde bien: "¿Dónde está la documentación? ¿Puedes enviarme un enlace?". Ahí es donde los equipos se encuentran con un muro. Bruno está diseñado para enviar solicitudes, no para publicar un portal de documentación compartible. Esta guía cubre honestamente la generación de documentación de API de Bruno, lo que Bruno te ofrece, lo que no, y cómo generar y alojar documentación desde tu especificación cuando necesitas una URL real para entregar a los consumidores.
Lo que los equipos realmente necesitan de la documentación de API
Antes de juzgar cualquier herramienta, ayuda definir el objetivo. Cuando la gente dice "documentación de API", generalmente se refieren a tres cosas que funcionan juntas:
- Una URL compartible. Los desarrolladores frontend, socios y QA necesitan leer la documentación sin clonar tu repositorio o instalar un cliente. Un enlace en Slack debería simplemente funcionar.
- Documentación que se mantiene sincronizada. La documentación que se desvía de la API real es peor que ninguna, porque envía a la gente en la dirección equivocada con confianza. La documentación debe seguir la especificación.
- Una experiencia interactiva de "probarlo". Leer descripciones de endpoints está bien; enviar una solicitud real contra el endpoint documentado, con autenticación y payloads de ejemplo rellenados, es lo que convierte la documentación en una referencia utilizable.
Cumple con los tres y tu documentación se convierte en la única fuente de verdad. Si falta uno, la gente recurre a preguntarte directamente, lo cual no escala.
La historia de la documentación de Bruno
Seamos justos con Bruno, porque hace algunas cosas bien aquí.
Las colecciones de Bruno son legibles por humanos. El formato .bru es texto plano, por lo que un ingeniero que navegue por el repositorio puede abrir un archivo de solicitud y ver el método, la URL, los encabezados y el cuerpo. Bruno también admite un bloque docs por solicitud y una vista de documentación en Markdown dentro de la aplicación, para que puedas adjuntar texto que explique lo que hace un endpoint. Como todo está en Git, esas notas se revisan en solicitudes pull como cualquier otro cambio. Para un equipo interno que vive en la base de código, esa es una forma legítima de documentación.
La brecha honesta es la publicación. Bruno no tiene un portal de documentación pública incorporado, alojado y generado automáticamente. No hay un botón de "publicar" que convierta tu colección en un sitio web con una URL estable y un dominio personalizado. La vista de documentación en la aplicación es visible para las personas que ya tienen Bruno instalado y han clonado la colección, que es exactamente la audiencia que menos necesita la documentación.
Así que los equipos improvisan. Las soluciones comunes incluyen exportar la colección o un archivo OpenAPI y alimentarlo a un generador de documentos estáticos separado, configurar un sitio de documentación en CI, o mantener un README escrito a mano que alguien actualiza de memoria. Esto puede funcionar, pero añade una tubería de construcción que mantener y un segundo lugar donde la información puede desviarse. La documentación ya no es un producto de primera clase de la herramienta con la que pruebas; es un proyecto secundario.
El principio "documentación como código"
Una forma más limpia de pensar en esto, y es una que los usuarios de Bruno ya medio creen: trata tu documentación como un producto de tu especificación, no como un artefacto separado.
En un flujo de trabajo de documentación como código, tu API se describe una vez en una especificación legible por máquina, típicamente OpenAPI. Esa especificación vive en Git, se revisa en solicitudes pull y actúa como contrato. La documentación, los servidores simulados y los SDK de cliente se generan todos a partir de ella. Cuando el contrato cambia, el cambio se revisa en un solo lugar y todo lo posterior lo sigue.
La ventaja es que no hay una tarea separada de "actualizar la documentación" que olvidar. La documentación es una representación de la especificación. Si la especificación es correcta y revisada, la documentación es correcta. Este es el principio al que Bruno alude al mantener las colecciones en Git, pero se queda corto en el paso de publicación.
Genera y aloja la documentación desde tu especificación en su lugar
Esta es la brecha que Apidog está diseñado para cerrar. Apidog mantiene el mismo modelo mental centrado en la especificación y amigable con Git, luego añade la pieza que Bruno omite: genera un sitio de documentación interactivo y alojado directamente desde tu especificación, sin necesidad de una tubería de construcción separada.
Apúntale a Apidog tu especificación OpenAPI y este producirá un portal de documentación automáticamente. El resultado es:
- Alojado en una URL compartible, para que cualquiera con el enlace pueda leer la documentación sin instalar nada.
- Montable en un dominio personalizado, para que la documentación pueda vivir en
docs.tuempresa.comy coincidir con tu marca. - Interactivo, con un panel incorporado de "probarlo" que envía solicitudes reales utilizando los parámetros, encabezados y autenticación documentados.
- Generado a partir de la especificación, para que la documentación refleje lo que la API realmente declara en lugar de una copia escrita a mano que puede desviarse.
Debido a que la misma especificación también impulsa las pruebas y la simulación de Apidog, no estás manteniendo tres descripciones de una misma API. La describes una vez y la reutilizas.
Tutorial: de la especificación a una URL compartible
Aquí está la versión corta de la publicación de documentación desde una especificación OpenAPI.
| Paso | Acción | Resultado |
|---|---|---|
| 1 | Importa o escribe tu especificación OpenAPI en Apidog | Los endpoints, esquemas y ejemplos se rellenan automáticamente |
| 2 | Abre la configuración de documentación del proyecto | La documentación se genera desde la especificación, lista para configurar |
| 3 | Elige la visibilidad y (opcionalmente) un dominio personalizado | La documentación es pública, privada o protegida con contraseña |
| 4 | Publicar | Se crea un sitio de documentación alojado y en vivo con una URL estable |
| 5 | Comparte el enlace | Los consumidores leen la documentación y ejecutan solicitudes de "probarlo" |
Si ya tienes una colección de Bruno, puedes convertirla a OpenAPI primero, luego importar esa especificación. A partir de ahí, el paso de publicación es el mismo. El punto es que generar y alojar la documentación es un hecho, no una tubería que tú mismo ensamblas.
Mantener la documentación sincronizada a medida que cambia la especificación
Una URL de documentación solo es útil si se mantiene precisa. El modo de fallo con las configuraciones improvisadas es que alguien implementa un cambio de endpoint y olvida la documentación.
Cuando la documentación se genera a partir de la especificación, ese riesgo disminuye. Editas la especificación, el cambio de la especificación pasa por revisión como cualquier otro cambio de código, y la documentación publicada refleja el nuevo estado. No hay un documento paralelo que recordar. Añade un campo a un esquema de respuesta y aparece en la documentación; depreca un endpoint y la documentación lo dice. El trabajo que ya haces para mantener el contrato correcto es el mismo trabajo que mantiene la documentación correcta.
Esta es la recompensa práctica del principio "documentación como código": la corrección se convierte en un efecto secundario de un flujo de trabajo que querrías de todos modos, en lugar de una tarea separada que depende de la disciplina.
Preguntas frecuentes
¿Puede Bruno generar y alojar documentación pública de API?
Bruno proporciona archivos de colección .bru legibles y una vista de documentación Markdown en la aplicación, ambos revisados en Git. No incluye un portal de documentación pública incorporado, alojado y generado automáticamente con una URL compartible. Para publicar documentación pública desde Bruno, los equipos suelen exportar una especificación y ejecutar un generador de documentos estáticos separado, lo que añade una tubería que mantener.
¿Cómo obtengo una URL de documentación compartible de mi API?
Describe tu API en una especificación OpenAPI, luego usa una herramienta que genere documentación alojada a partir de ella. En Apidog, importas la especificación, configuras la visibilidad, opcionalmente adjuntas un dominio personalizado y publicas. El resultado es un sitio de documentación en vivo con una URL estable, con un panel interactivo de "probarlo", que puedes compartir directamente.
¿Tengo que abandonar mis colecciones de Bruno para publicar la documentación?
No. Puedes convertir una colección existente de Bruno a OpenAPI e importar esa especificación a una herramienta de documentación. Tus endpoints, esquemas y ejemplos se trasladan, y mantienes la especificación bajo control de versiones. La migración es a nivel de especificación, por lo que los hábitos de "documentación como código" que construiste con Bruno siguen siendo aplicables.