Cómo Generar y Alojar Documentación API con Bruno

Si ya adoptaste Bruno, probablemente lo hiciste por una razón clara: tus colecciones viven como archivos .bru en Git, versionadas junto al código y sin depender de una cuenta en la nube. Es una opción limpia, offline-first y útil cuando el equipo quiere mantener el control de sus datos.

Prueba Apidog hoy

Pero en algún momento aparece una necesidad práctica: “¿Dónde está la documentación? ¿Puedes enviarme un enlace?”. Ahí Bruno se queda corto. Bruno está pensado para enviar solicitudes, no para publicar un portal de documentación compartible. Esta guía explica qué puedes documentar con Bruno, qué no resuelve y cómo generar una URL real de documentación a partir de una especificación OpenAPI.

Lo que necesitas de una documentación de API útil

Antes de elegir una herramienta, define el resultado esperado. En la práctica, una buena documentación de API debe cubrir tres requisitos:

• Una URL compartible: frontend, QA, partners o consumidores externos deberían poder abrir un enlace sin clonar un repositorio ni instalar un cliente.
• Sincronización con la API real: la documentación debe salir de una especificación o contrato actualizado, no de texto duplicado que puede quedar obsoleto.
• Una experiencia interactiva: además de leer endpoints, los usuarios deberían poder probar solicitudes con parámetros, headers, autenticación y ejemplos.

Si falta cualquiera de estos puntos, el equipo termina respondiendo preguntas manualmente, lo que no escala.

Qué ofrece Bruno para documentación

Bruno sí tiene elementos útiles para documentar APIs dentro del flujo de trabajo del equipo.

Las colecciones .bru son archivos de texto plano. Eso permite revisar en Git información como:

GET /users/{id}
headers
body
auth

Además, Bruno permite agregar un bloque docs por solicitud y ver documentación en Markdown dentro de la aplicación. Esto sirve para explicar qué hace un endpoint, cómo se usa o qué casos especiales hay que considerar.

Para equipos internos que ya trabajan dentro del repositorio, este enfoque funciona bien:

1. El endpoint vive en un archivo .bru.
2. Las notas se escriben en Markdown.
3. Los cambios se revisan en pull requests.
4. La documentación queda versionada junto con el código.

El problema aparece cuando necesitas publicar esa documentación fuera del entorno de Bruno.

La limitación: Bruno no publica un portal de documentación

Bruno no incluye un portal público de documentación generado automáticamente. No hay un botón de “publicar” que convierta tu colección en un sitio web con:

• URL estable.
• Dominio personalizado.
• Vista pública o protegida.
• Panel interactivo para probar endpoints.
• Generación automática desde una especificación.

La vista de documentación de Bruno está orientada a personas que ya tienen Bruno instalado y han clonado la colección. Es decir, justo el público que menos necesita una URL de documentación.

Por eso muchos equipos terminan armando soluciones manuales:

• Exportar la colección.
• Convertirla a OpenAPI.
• Usar un generador estático de documentación.
• Publicar el sitio en CI/CD.
• Mantener un README con ejemplos actualizados a mano.

Esto puede funcionar, pero añade mantenimiento. También crea un segundo lugar donde la información puede desactualizarse.

Usa documentación como código

Una forma más sostenible es tratar la documentación como una salida de tu especificación, no como un documento separado.

En un flujo de documentación como código, describes la API una vez en una especificación legible por máquina, normalmente OpenAPI.

Esa especificación puede vivir en Git y pasar por revisión como cualquier otro archivo del proyecto:

openapi: 3.0.3
info:
  title: API de usuarios
  version: 1.0.0
paths:
  /users/{id}:
    get:
      summary: Obtener usuario por ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Usuario encontrado

Desde esa especificación puedes generar:

• Documentación.
• Mocks.
• Pruebas.
• SDKs.
• Contratos revisables en pull requests.

La ventaja es simple: no actualizas la documentación como tarea separada. Actualizas el contrato y la documentación se genera desde él.

Genera y aloja documentación desde tu especificación

Aquí es donde Apidog cubre la parte que Bruno no resuelve: generar un sitio de documentación interactivo y alojado directamente desde la especificación, sin montar una tubería de build aparte.

El flujo es directo:

1. Importas o defines tu especificación OpenAPI.
2. Apidog genera la documentación desde esa especificación.
3. Configuras visibilidad y, si lo necesitas, dominio personalizado.
4. Publicas.
5. Compartes la URL con consumidores de la API.

El resultado es una documentación:

• Alojada en una URL compartible.
• Montable en un dominio como docs.tuempresa.com.
• Interactiva, con opción de probar solicitudes reales.
• Generada desde la especificación, no desde texto duplicado.
• Reutilizable junto con pruebas y simulación dentro del mismo flujo.

Tutorial: de OpenAPI a una URL compartible

Usa este flujo si ya tienes una especificación OpenAPI o si puedes convertir tu colección de Bruno a 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 puede ser pública, privada o protegida con contraseña
4	Publica	Se crea un sitio de documentación alojado con una URL estable
5	Comparte el enlace	Los consumidores leen la documentación y ejecutan solicitudes de prueba

Si partes desde Bruno, el flujo recomendado es:

Colección Bruno
      ↓
Exportar o convertir a OpenAPI
      ↓
Importar especificación en Apidog
      ↓
Generar documentación
      ↓
Publicar URL compartible

La clave es mover la fuente de verdad a una especificación. A partir de ahí, la documentación deja de ser un proyecto manual y pasa a ser una salida generada.

Mantén la documentación sincronizada

Una URL de documentación solo sirve si refleja el estado real de la API.

El flujo recomendado es:

1. Cambia la especificación cuando cambie la API.
2. Revisa ese cambio en Git o en el flujo de revisión del equipo.
3. Publica la documentación generada desde la especificación.
4. Comparte siempre la misma URL estable.

Por ejemplo, si agregas un campo a una respuesta:

responses:
  "200":
    description: Usuario encontrado
    content:
      application/json:
        schema:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
            email:
              type: string

Ese cambio debe aparecer en la documentación generada. No deberías tener que actualizar otro documento a mano.

Lo mismo aplica si:

• Agregas un endpoint.
• Cambias un esquema.
• Marcas un endpoint como obsoleto.
• Añades ejemplos de request o response.
• Actualizas parámetros o headers.

El trabajo de mantener correcto el contrato es el mismo trabajo que mantiene correcta la documentación.

Cuándo usar Bruno y cuándo publicar con una herramienta externa

Bruno sigue siendo útil si tu prioridad es:

• Trabajar offline.
• Versionar colecciones en Git.
• Ejecutar solicitudes desde un cliente local.
• Mantener notas internas por endpoint.

Pero si necesitas documentación consumible por otras personas, necesitas una capa de publicación.

Usa documentación alojada cuando:

• QA necesita consultar endpoints sin instalar Bruno.
• Frontend necesita una referencia estable.
• Tienes consumidores externos.
• Quieres compartir documentación por Slack, correo o portal interno.
• Necesitas una experiencia interactiva de “probarlo”.
• Quieres evitar mantener un sitio de documentación manual.

Preguntas frecuentes

¿Puede Bruno generar y alojar documentación pública de API?

Bruno proporciona archivos .bru legibles y una vista de documentación Markdown dentro de la aplicación. También permite versionar esa información en Git. Sin embargo, no incluye un portal público de documentación alojado y generado automáticamente con una URL compartible.

Para publicar documentación pública desde Bruno, normalmente necesitas exportar o convertir la información a una especificación y usar una herramienta de documentación aparte.

¿Cómo obtengo una URL compartible para la documentación de mi API?

Describe tu API en una especificación OpenAPI y usa una herramienta que genere documentación alojada desde esa especificación.

En Apidog, el flujo es:

1. Importar la especificación.
2. Configurar la documentación.
3. Definir visibilidad.
4. Opcionalmente, adjuntar un dominio personalizado.
5. Publicar.

El resultado es una URL estable que puedes compartir con consumidores de la API.

¿Tengo que abandonar mis colecciones de Bruno?

No necesariamente. Puedes convertir una colección existente de Bruno a OpenAPI e importar esa especificación en una herramienta de documentación.

La migración ocurre a nivel de especificación. Eso permite mantener el enfoque de “documentación como código” mientras añades una capa de publicación para compartir la documentación.

¿Cuál es la idea principal?

Bruno funciona bien para colecciones versionadas y trabajo local. Pero si necesitas documentación pública, compartible e interactiva, necesitas generar y alojar esa documentación desde una especificación como OpenAPI.

La forma más mantenible es:

Especificación como fuente de verdad
      ↓
Documentación generada
      ↓
URL compartible
      ↓
Consumidores probando la API

Así evitas documentación duplicada, reduces desactualizaciones y entregas una referencia útil para quienes consumen tu API.