Se você adotou o Bruno, você já conhece o apelo. Suas coleções vivem como arquivos .bru simples no seu repositório Git, versionadas junto com o código, sem necessidade de conta na nuvem. É uma resposta limpa e offline-first para clientes de API que desejam ter controle sobre seus dados.
Mas, cedo ou tarde, alguém faz uma pergunta que o Bruno não responde bem: “Onde estão os docs? Você pode me enviar um link?” É aí que as equipes encontram um obstáculo. O Bruno é feito para enviar requisições, não para publicar um portal de documentação compartilhável. Este guia aborda a geração de documentação de API do Bruno honestamente, o que o Bruno oferece, o que não oferece e como gerar e hospedar documentação a partir da sua especificação quando você precisa de uma URL real para entregar aos consumidores.
O que as equipes realmente precisam da documentação de API
Antes de julgar qualquer ferramenta, é útil definir o objetivo. Quando as pessoas dizem “documentação de API”, geralmente se referem a três coisas trabalhando juntas:
- Uma URL compartilhável. Desenvolvedores frontend, parceiros e QA precisam ler a documentação sem clonar seu repositório ou instalar um cliente. Um link no Slack deve simplesmente funcionar.
- Documentação que permanece sincronizada. A documentação que se desvia da API real é pior do que nenhuma, porque envia as pessoas na direção errada com confiança. A documentação deve seguir a especificação.
- Uma experiência interativa de “experimente”. Ler descrições de endpoints é bom; enviar uma requisição real para o endpoint documentado, com autenticação e payloads de exemplo preenchidos, é o que transforma a documentação em uma referência utilizável.
Acerte os três e sua documentação se torna a única fonte da verdade. Perca um e as pessoas voltam a perguntar diretamente a você, o que não escala.
A história da documentação do Bruno
Sejamos justos com o Bruno, porque ele faz algumas coisas bem aqui.
As coleções do Bruno são legíveis por humanos. O formato .bru é texto simples, então um engenheiro navegando no repositório pode abrir um arquivo de requisição e ver o método, URL, cabeçalhos e corpo. O Bruno também suporta um bloco docs por requisição e uma visualização de documentação em Markdown dentro do aplicativo, para que você possa anexar texto explicando o que um endpoint faz. Como tudo está no Git, essas notas são revisadas em pull requests como qualquer outra alteração. Para uma equipe interna que vive na base de código, essa é uma forma legítima de documentação.
A lacuna honesta é a publicação. O Bruno não possui um portal de documentação pública embutido, hospedado e gerado automaticamente. Não há um botão de “publicar” que transforme sua coleção em um site com uma URL estável e um domínio personalizado. A visualização de documentação no aplicativo é visível para pessoas que já têm o Bruno instalado e clonaram a coleção, que é exatamente o público que menos precisa de documentação.
Então as equipes improvisam. Soluções alternativas comuns incluem exportar a coleção ou um arquivo OpenAPI e alimentá-lo em um gerador de documentação estática separado, configurar um site de documentação em CI, ou manter um README escrito à mão que alguém atualiza de memória. Isso pode funcionar, mas adiciona um pipeline de build para manter e um segundo lugar onde a informação pode se desviar. A documentação deixa de ser uma saída de primeira classe da ferramenta que você testa; torna-se um projeto secundário.
O princípio docs-as-code
Uma maneira mais limpa de pensar sobre isso, e que os usuários do Bruno já meio que acreditam: trate sua documentação como um produto da sua especificação, não como um artefato separado.
Em um workflow docs-as-code, sua API é descrita uma única vez em uma especificação legível por máquina, tipicamente OpenAPI. Essa especificação reside no Git, é revisada em pull requests e atua como o contrato. Documentação, mock servers e SDKs de cliente são todos gerados *a partir* dela. Quando o contrato muda, a alteração é revisada em um único lugar, e tudo o que está a jusante segue.
A vantagem é que não há uma tarefa separada de “atualizar a documentação” para esquecer. A documentação é uma renderização da especificação. Se a especificação estiver correta e revisada, a documentação estará correta. Este é o princípio que o Bruno sugere ao manter as coleções no Git, mas fica aquém da etapa de publicação.
Gere e hospede a documentação a partir da sua especificação
Esta é a lacuna que o Apidog foi construído para fechar. O Apidog mantém o mesmo modelo mental centrado na especificação e amigável ao Git, então adiciona a peça que o Bruno deixa de fora: ele gera um site de documentação interativo e hospedado diretamente da sua especificação, sem necessidade de pipeline de build separado.
Aponte o Apidog para sua especificação OpenAPI e ele produzirá um portal de documentação automaticamente. O resultado é:
- Hospedado em uma URL compartilhável, para que qualquer pessoa com o link possa ler a documentação sem instalar nada.
- Montável em um domínio personalizado, para que a documentação possa residir em
docs.suaempresa.come corresponder à sua marca. - Interativo, com um painel “experimente” integrado que envia requisições reais usando os parâmetros, cabeçalhos e autenticação documentados.
- Gerado a partir da especificação, para que a documentação reflita o que a API realmente declara, em vez de uma cópia escrita à mão que pode se desviar.
Como a mesma especificação também impulsiona os testes e mocking do Apidog, você não está mantendo três descrições de uma API. Você a descreve uma vez e a reutiliza.
Passo a passo: da especificação à URL compartilhável
Aqui está a versão resumida de como publicar a documentação a partir de uma especificação OpenAPI.
| 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” |
Se você já tem uma coleção Bruno, pode convertê-la para OpenAPI primeiro e depois importar essa especificação. A partir daí, a etapa de publicação é a mesma. O ponto é que gerar e hospedar a documentação é um recurso, não um pipeline que você monta sozinho.
Mantendo a documentação sincronizada conforme a especificação muda
Uma URL de documentação só é útil se permanecer precisa. O modo de falha com configurações improvisadas é que alguém implementa uma alteração de endpoint e esquece a documentação.
Quando a documentação é gerada a partir da especificação, esse risco diminui. Você edita a especificação, a alteração da especificação passa por revisão como qualquer outra alteração de código, e a documentação publicada reflete o novo estado. Não há um documento paralelo para lembrar. Adicione um campo a um esquema de resposta e ele aparece na documentação; descontinue um endpoint e a documentação o informará. O trabalho que você já faz para manter o contrato correto é o mesmo trabalho que mantém a documentação correta.
Este é o benefício prático do princípio docs-as-code: a correção se torna um efeito colateral de um workflow que você desejaria de qualquer forma, em vez de uma tarefa separada que depende de disciplina.
FAQ
O Bruno pode gerar e hospedar documentação de API pública?
O Bruno fornece arquivos de coleção .bru legíveis e uma visualização de documentação Markdown no aplicativo, ambos revisados no Git. Ele não inclui um portal de documentação pública embutido, hospedado e gerado automaticamente com uma URL compartilhável. Para publicar documentação pública a partir do Bruno, as equipes geralmente exportam uma especificação e executam um gerador de documentação estática separado, o que adiciona um pipeline para manter.
Como obtenho uma URL de documentação compartilhável da minha API?
Descreva sua API em uma especificação OpenAPI e, em seguida, use uma ferramenta que gere documentação hospedada a partir dela. No Apidog, você importa a especificação, configura a visibilidade, opcionalmente anexa um domínio personalizado e publica. O resultado é um site de documentação ao vivo em uma URL estável, com um painel interativo de “experimente”, que você pode compartilhar diretamente.
Preciso abandonar minhas coleções Bruno para publicar a documentação?
Não. Você pode converter uma coleção Bruno existente para OpenAPI e importar essa especificação para uma ferramenta de documentação. Seus endpoints, schemas e exemplos são transferidos, e você mantém a especificação sob controle de versão. A migração ocorre na camada da especificação, então os hábitos docs-as-code que você construiu com o Bruno ainda se aplicam.