OasRails is a Rails engine for generating automatic interactive documentation for your Rails APIs. It generates an OAS 3.1 document and displays it using RapiDoc.
It relies on the OasCore gem.
Explore the interactive documentation live:
🔗 Open Demo App
👤 Username: oasrails
🔑 Password: oasrails
🎬 A Demo Installation/Usage Video: https://vimeo.com/1013687332 🎬
- ApiPie: Doesn't support OAS 3.1, requires learning a DSL, lacks a nice UI
- swagger_yard-rails: Seems abandoned, but serves as inspiration
- Rswag: Not automatic, depends on RSpec; Many developers now use Minitest as it's the default test framework
- grape-swagger: Requires Grape
- rspec_api_documentation: Requires RSpec and a command to generate the docs
- Dynamic: No command required to generate docs
- Simple: Complement default documentation with a few comments; no need to learn a complex DSL
- Pure Ruby on Rails APIs: No additional frameworks needed (e.g., Grape, RSpec)
After experiencing the interactive documentation in Python's fast-api framework, I sought similar functionality in Ruby on Rails. Unable to find a suitable solution, I asked on Stack Overflow years ago. Now, with some free time while freelancing as an API developer, I decided to build my own tool.
Note: This is not yet a production-ready solution. The code may be rough and behave unexpectedly, but I am actively working on improving it. If you like the idea, please consider contributing to its development.
The goal is to minimize the effort required to create comprehensive documentation. By following REST principles in Rails, we believe this is achievable. You can enhance the documentation using Yard tags.
For see how to install, configure and use OasRails please refere to the OasCore MDBook
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated. If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star⭐! Thanks again!
If you plan a big feature, first open an issue to discuss it before any development.
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
The gem is available as open source under the terms of the GPL-3.0.