Documentação de API sempre começa com boas intenções.
No início do projeto, tudo está sincronizado.
As rotas batem com a aplicação.
Os exemplos estão corretos.
Os parâmetros fazem sentido.
As respostas refletem exatamente o que a API retorna.
Mas conforme o sistema evolui, a documentação começa a ficar para trás.
Uma nova rota é criada.
Um parâmetro muda.
Um endpoint ganha autenticação.
Uma resposta recebe novos campos.
E, sem perceber, a documentação deixa de representar a realidade.
Se você trabalha com APIs em Rails há algum tempo, provavelmente já passou por isso.
Eu certamente já passei.
E foi justamente essa frustração que me levou a criar o rails-api-docs.
GitHub: https://github.com/jacksonpires/rails-api-docs
A ideia surgiu de uma pergunta simples
Sua aplicação Rails já sabe muita coisa.
Ela conhece:
- suas rotas
- seus controllers
- seus parâmetros
- seus modelos
- seu schema do banco
- seus verbos HTTP
Então por que a documentação precisa começar sempre do zero?
Por que precisamos reescrever manualmente informações que já existem dentro da aplicação?
A ideia por trás do rails-api-docs foi justamente aproveitar esse conhecimento que o Rails já possui para gerar um primeiro rascunho da documentação automaticamente.
O workflow que eu queria não existia
Eu não queria mais uma ferramenta onde o fluxo fosse:
editar documentação
→ gerar artefatos
→ rebuild
→ reiniciar servidor
→ validar alterações
Eu queria algo mais próximo do desenvolvimento Rails tradicional:
editar
→ atualizar navegador
→ continuar trabalhando
Foi daí que surgiu o conceito central da gem:
Um único arquivo YAML editável que gera tanto a documentação em desenvolvimento quanto a documentação de produção.
Uma única fonte da verdade
O fluxo da gem gira em torno de apenas um arquivo:
config/rails-api-docs.yml
Esse arquivo é a fonte da verdade para toda a documentação.
A partir dele a gem gera:
- visualização em tempo real durante o desenvolvimento
- exemplos de requisição
- exemplos de resposta
- schemas documentados
- documentação HTML estática para produção
Você altera um único lugar.
Todo o resto é atualizado automaticamente.
Como funciona
Primeiro você gera o YAML inicial:
rails g rails-api-docs:init
A gem inspeciona automaticamente:
Rails.application.routes- controllers (via análise AST usando Prism)
- schema do ActiveRecord
E cria uma estrutura inicial de documentação.
Depois basta subir a aplicação:
rails server
E acessar:
http://localhost:3000/rails/api-docs
Sempre que você alterar o YAML, basta atualizar a página.
Não existe etapa de build durante o desenvolvimento.
Não existe pipeline frontend.
Não existe processo intermediário.
Deixe o código escrever o primeiro rascunho
Uma das partes mais interessantes do projeto foi utilizar o Prism para analisar controllers.
Por exemplo:
params.require(:user).permit(
:email,
:password,
:role
)
A gem consegue identificar automaticamente esses campos e utilizá-los para montar a estrutura inicial da documentação.
Quando combinamos isso com as informações do ActiveRecord, também é possível inferir:
- tipos dos campos
- obrigatoriedade
- exemplos iniciais
- informações do schema
O objetivo nunca foi substituir o trabalho do desenvolvedor.
O objetivo foi eliminar tarefas repetitivas.
Deixar a máquina fazer aquilo que ela consegue descobrir sozinha.
E deixar os humanos cuidarem da parte importante: explicar a API.
Atualizações não deveriam apagar seu trabalho
Essa talvez seja a característica que mais me incomodava em algumas abordagens existentes.
Você gera documentação.
Investe tempo escrevendo descrições.
Adiciona exemplos.
Organiza seções.
Personaliza schemas.
Então roda novamente o gerador.
E precisa rezar para não perder nada.
No rails-api-docs o YAML segue uma estratégia append-only.
Quando você adiciona novas rotas à aplicação basta executar:
rails g rails-api-docs:update
A gem adiciona apenas os endpoints novos.
Todo o conteúdo que você escreveu continua intacto.
Isso inclui:
- descrições
- exemplos
- tags
- autenticação
- schemas
- organização das seções
Na prática, a documentação deixa de ser um artefato descartável e passa a ser um documento vivo.
Organizando APIs maiores com Tags
Conforme uma API cresce, navegar pela documentação pode ficar mais difícil.
Por isso a gem possui suporte a tags:
tags:
- auth
- public
Essas tags não são apenas informativas.
Elas também funcionam como filtros interativos na documentação gerada.
Ao clicar em uma tag, a navegação passa a exibir apenas os endpoints relacionados àquela categoria.
Isso facilita bastante a exploração de APIs maiores.
Produção deveria ser simples
Outro objetivo importante era simplificar o deploy da documentação.
Quando chega o momento de publicar, basta executar:
rake rails-api-docs:build
O resultado é:
public/api-docs.html
Um único arquivo HTML.
Tudo embutido.
CSS inline.
JavaScript inline.
Sem dependências externas.
Sem CDN.
Sem Asset Pipeline.
Sem runtime JavaScript.
Apenas um arquivo estático que pode ser hospedado praticamente em qualquer lugar.
Não estou tentando substituir OpenAPI
Existem excelentes ferramentas baseadas em OpenAPI e Swagger.
Elas resolvem muito bem diversos cenários.
O objetivo do rails-api-docs não é substituir esse ecossistema.
A proposta é diferente.
Eu queria uma solução que permitisse:
- gerar documentação a partir de uma aplicação Rails existente
- editar tudo em YAML
- visualizar mudanças instantaneamente
- exportar um HTML estático
- manter a documentação sincronizada com pouco esforço
Era esse workflow que eu procurava.
E como não encontrei exatamente dessa forma, resolvi construir.
Considerações finais
Documentação de API deveria ser simples de criar e simples de manter.
Na minha experiência, o maior problema não é gerar a primeira versão.
O desafio é mantê-la atualizada ao longo do tempo.
O rails-api-docs nasceu justamente para reduzir esse atrito.
Inspecionando a aplicação para gerar um ponto de partida.
Preservando suas customizações ao longo do tempo.
E oferecendo um ciclo de feedback extremamente rápido durante o desenvolvimento.
Se quiser experimentar:
⭐ https://github.com/jacksonpires/rails-api-docs
Feedbacks, sugestões e contribuições são muito bem-vindos.
Top comments (0)