Anyone who works with Ruby on Rails knows that, despite the framework being incredible for productivity, there are some classic workflow deficiencies that haunt almost every project.
You are focused on writing code, but suddenly you need to open an external tool like Postman to test a route. Then, you run a complex script to generate a static database diagram. And at the end of the day, you still need to manually update the API documentation, which will inevitably become outdated in the next sprint.
This constant context switching and manual maintenance generates enormous friction. To cover these deficiencies, I developed three gems that bring these tools inside your application. They are so practical that they quickly become indispensable in any Rails project. Meet each one of them:
1. rails-api-docs: The End of Outdated Documentation
The deficiency: API documentation always starts with good intentions, but as the system evolves—new routes, parameters, and response fields—it quickly stops representing reality. Keeping this updated manually is repetitive and frustrating work.
The solution: The rails-api-docs gem solves this by leveraging what Rails already knows. It inspects your routes, controllers (via AST analysis using Prism), and the ActiveRecord schema to automatically generate the first draft of your documentation. Everything is saved in a single YAML file (config/rails-api-docs.yml), which serves as the single source of truth.
Why it is indispensable:
- Append-only strategy: When adding new routes and running the generator, the gem only appends what's new. Your descriptions, custom examples, and tags are never modified or deleted, making the documentation a living document.
-
Zero development friction: You edit the YAML in one window and view the updated documentation in the browser at
localhost:3000/rails/api-docsinstantly, with no build step required. For production, it exports a single static HTML file without any external dependencies.
2. rails-http-lab: Your HTTP Client Right in the App
The deficiency: Testing HTTP endpoints usually requires switching to external tools (like Postman or Insomnia) or creating temporary scripts. Besides the loss of focus, these tools live outside your repository and frequently suffer from CORS issues when trying to access internal services.
The solution: The rails-http-lab is a Rails Engine that couples an HTTP request lab inside your own application. By accessing /rails/http-lab, you have a lightweight interface to test methods, headers, and payloads while visualizing the responses directly in the browser.
Why it is indispensable:
-
Stays in the Repository: Your requests are saved in
.bruformat (interchangeable with the Bruno desktop app) inside the project'sdocs/http-lab/folder. This means your API tests are version-controlled in Git and can be easily reviewed in Pull Requests. - No CORS limits: Since the requests are executed by the Rails server itself, you don't have CORS problems and can reach internal services transparently.
3. rails-realtime-erd: Database Diagrams Always in Sync
The deficiency: Understanding database relationships in a growing project is difficult. Traditional tools generate static diagrams (ERD) that require manual tasks and quickly become outdated as soon as a new migration is executed.
The solution: The rails-realtime-erd gem mounts a route at /rails/erd that renders your schema diagram in real-time using Mermaid, all processed by Hotwire (Stimulus), without relying on complex JavaScript frameworks.
Why it is indispensable:
You will never again need to run a rake step to generate a static image file. The introspection is done on the fly: if you run a migration, just refresh the page to see the new tables and relationships reflected in the diagram immediately. It is excellent for onboarding new developers and keeping a live documentation of your architecture.
Conclusion
These three tools share the same philosophy: your code already has the necessary knowledge, and the support tools should live as close to it as possible.
Adopting rails-api-docs, rails-http-lab, and rails-realtime-erd drastically reduces daily friction, eliminating external dependencies and manual rework. With simple installation steps, your development environment will become much more productive, robust, and integrated.
Top comments (0)