Se você adotou o Bruno, provavelmente foi pelo fluxo offline-first: coleções em arquivos .bru, versionadas no Git junto com o código e sem dependência de uma conta na nuvem. Isso funciona bem para testar APIs internamente, mas cria uma lacuna quando alguém pergunta: “onde está a documentação pública?” ou “você pode me enviar um link?”.
O Bruno é ótimo para enviar requisições e manter coleções no repositório. Ele não foi projetado, porém, para publicar um portal de documentação hospedado, compartilhável e interativo. Neste guia, você verá o que o Bruno entrega, onde ele para e como transformar sua especificação OpenAPI em uma URL de documentação utilizável por frontend, QA, parceiros e consumidores externos.
O que uma documentação de API precisa entregar
Antes de escolher uma ferramenta, defina o resultado esperado. Na prática, uma documentação de API útil precisa de três coisas:
- Uma URL compartilhável: consumidores devem conseguir abrir a documentação sem clonar o repositório ou instalar um cliente de API.
- Sincronização com o contrato da API: se a especificação muda, a documentação também precisa refletir essa mudança.
- Execução interativa de requisições: além de ler endpoints, o usuário deve conseguir testar chamadas com parâmetros, headers, autenticação e exemplos.
Quando esses três pontos existem, a documentação vira referência operacional. Quando falta um deles, o time volta a responder dúvidas manualmente.
O que o Bruno oferece para documentação
O Bruno tem uma base interessante para documentação interna.
As coleções são armazenadas em arquivos .bru, que são texto simples. Isso permite abrir uma requisição no repositório e inspecionar método, URL, headers e body. O Bruno também suporta um bloco docs por requisição e uma visualização Markdown dentro do aplicativo.
Exemplo conceitual de uma requisição documentada em .bru:
meta {
name: Criar usuário
type: http
}
post {
url: {{baseUrl}}/users
body: json
auth: bearer
}
headers {
Content-Type: application/json
}
body:json {
{
"name": "Ana",
"email": "ana@example.com"
}
}
docs {
Cria um novo usuário no sistema.
Campos obrigatórios:
- name
- email
}
Esse modelo funciona bem quando:
- todo o time usa Bruno;
- todos têm acesso ao repositório;
- a documentação é consumida principalmente por engenheiros internos;
- a revisão acontece via pull request.
A limitação aparece na publicação.
O Bruno não inclui um portal de documentação pública hospedado, gerado automaticamente e acessível por uma URL estável. A visualização de documentação existe dentro do app, mas depende de o usuário ter o Bruno instalado e a coleção clonada.
O problema: documentação vira um pipeline paralelo
Quando a equipe precisa publicar documentação fora do Bruno, o caminho comum costuma ser:
- exportar a coleção ou gerar uma especificação OpenAPI;
- usar um gerador estático de documentação;
- configurar hospedagem;
- manter um pipeline de build;
- garantir que tudo continue sincronizado.
Esse fluxo funciona, mas adiciona manutenção.
O risco é criar duas fontes de verdade:
- a coleção usada para testar;
- a documentação publicada para consumidores.
Quando elas divergem, a documentação perde confiabilidade.
Use docs-as-code como princípio
Uma abordagem mais sustentável é tratar a documentação como saída da especificação, não como um documento separado.
Em um fluxo docs-as-code, a API é descrita em uma especificação legível por máquina, normalmente OpenAPI. Essa especificação fica no Git, passa por pull requests e funciona como contrato.
A partir dela, você pode gerar:
- documentação;
- mocks;
- testes;
- SDKs;
- exemplos de requisição.
O ponto principal é simples: edite o contrato uma vez e gere os artefatos a partir dele.
Um exemplo mínimo de OpenAPI:
openapi: 3.0.3
info:
title: API de Usuários
version: 1.0.0
servers:
- url: https://api.exemplo.com
paths:
/users:
post:
summary: Criar usuário
description: Cria um novo usuário no sistema.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
- email
properties:
name:
type: string
example: Ana
email:
type: string
format: email
example: ana@example.com
responses:
"201":
description: Usuário criado
Com esse contrato, a documentação não precisa ser reescrita manualmente. Ela pode ser renderizada a partir da especificação.
Gere e hospede documentação a partir da especificação
É aqui que o Apidog entra no fluxo.
O Apidog trabalha com uma abordagem centrada na especificação e permite gerar um portal de documentação interativo e hospedado diretamente da sua OpenAPI, sem montar um pipeline separado de documentação estática.
Na prática, você pode:
- importar uma especificação OpenAPI;
- gerar documentação automaticamente;
- publicar em uma URL compartilhável;
- configurar domínio personalizado;
- permitir testes interativos com o painel “experimente”;
- manter a documentação alinhada à especificação.
Como a mesma especificação também pode alimentar testes e mocks, você evita manter descrições duplicadas da mesma API.
Passo a passo: da especificação à URL pública
Use este fluxo quando você já tiver uma especificação OpenAPI ou puder gerar uma a partir da coleção Bruno.
| Etapa | Ação | Resultado |
|---|---|---|
| 1 | Importe ou escreva sua especificação OpenAPI no Apidog | Endpoints, schemas e exemplos são preenchidos automaticamente |
| 2 | Abra as configurações de documentação do projeto | A documentação é gerada a partir da especificação, pronta para configurar |
| 3 | Escolha a visibilidade e (opcionalmente) um domínio personalizado | A documentação pode ser pública, privada ou protegida por senha |
| 4 | Publique | Um site de documentação ao vivo e hospedado é criado em uma URL estável |
| 5 | Compartilhe o link | Os consumidores leem a documentação e executam requisições “experimente” |
Fluxo recomendado:
Coleção Bruno
↓
Exportação/conversão para OpenAPI
↓
Importação no Apidog
↓
Geração da documentação
↓
Publicação em URL compartilhável
Se você já mantém OpenAPI no Git, o fluxo fica ainda mais direto:
openapi.yaml
↓
Apidog
↓
Documentação hospedada + testes interativos
Como manter a documentação sincronizada
Uma documentação publicada só é útil se permanecer correta. O problema em setups manuais é que alguém altera a API e esquece de atualizar o site de docs.
Com documentação gerada a partir da especificação, o processo fica mais previsível:
- o desenvolvedor altera a especificação;
- a mudança passa por revisão no pull request;
- a documentação publicada reflete o novo contrato;
- consumidores acessam a versão atualizada.
Exemplo: se você adiciona um campo ao schema de resposta, ele aparece na documentação gerada. Se remove ou descontinua um endpoint, essa mudança também passa pelo contrato.
O trabalho de manter a especificação correta passa a ser o mesmo trabalho de manter a documentação correta.
Quando usar Bruno, OpenAPI e Apidog juntos
Uma forma prática de organizar o fluxo é:
- use Bruno para coleções locais e testes internos versionados no Git;
- use OpenAPI como contrato formal da API;
- use Apidog para gerar documentação hospedada, interativa e compartilhável.
Isso evita abandonar o que já funciona no Bruno, mas resolve a parte que ele não cobre nativamente: publicação de documentação.
FAQ
O Bruno pode gerar e hospedar documentação pública de API?
O Bruno fornece arquivos .bru legíveis e uma visualização Markdown dentro do aplicativo. Esses recursos funcionam bem para documentação interna versionada no Git.
Ele não inclui, porém, um portal público hospedado, gerado automaticamente e acessível por uma URL compartilhável. Para publicar documentação pública, normalmente é necessário exportar ou converter a coleção para uma especificação e usar outra ferramenta de documentação.
Como obtenho uma URL compartilhável para minha documentação de API?
Descreva sua API em OpenAPI e use uma ferramenta que gere documentação hospedada a partir dessa especificação.
No Apidog, o fluxo é:
- importar a especificação;
- configurar visibilidade;
- opcionalmente definir domínio personalizado;
- publicar;
- compartilhar a URL gerada.
O resultado é um site de documentação com endpoints, schemas, exemplos e painel interativo de teste.
Preciso abandonar minhas coleções Bruno?
Não. Você pode continuar usando Bruno para coleções locais e converter a coleção para OpenAPI quando precisar publicar documentação.
A migração acontece na camada da especificação. Assim, você mantém o hábito docs-as-code e adiciona uma etapa de publicação mais adequada para consumidores externos.
Qual é a melhor fonte da verdade: coleção ou especificação?
Para documentação pública e integrações externas, a especificação OpenAPI costuma ser a melhor fonte da verdade, porque é legível por ferramentas e pode gerar documentação, mocks, testes e clientes.
A coleção pode continuar útil para execução local e fluxos internos, mas a documentação publicada deve vir do contrato formal da API.
Top comments (0)