https://github.com/a-chacon/oas_rails
Generate Automatic Interactive Documentation for Your Rails API
https://github.com/a-chacon/oas_rails
api api-rest documentation oas oas3 openapi openapi31 rails rapidoc ruby swagger swagger-ui
Last synced: 6 months ago
JSON representation
Generate Automatic Interactive Documentation for Your Rails API
- Host: GitHub
- URL: https://github.com/a-chacon/oas_rails
- Owner: a-chacon
- License: gpl-3.0
- Created: 2024-07-21T16:44:36.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-11T21:47:27.000Z (6 months ago)
- Last Synced: 2025-04-11T22:36:38.454Z (6 months ago)
- Topics: api, api-rest, documentation, oas, oas3, openapi, openapi31, rails, rapidoc, ruby, swagger, swagger-ui
- Language: Ruby
- Homepage: https://a-chacon.com/oas_rails
- Size: 2.05 MB
- Stars: 96
- Watchers: 4
- Forks: 12
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# 📃Open API Specification For Rails
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](https://rapidocweb.com)**.
🎬 A Demo Video Here:
🎬
## Related Projects
- **[ApiPie](https://github.com/Apipie/apipie-rails)**: Doesn't support OAS 3.1, requires learning a DSL, lacks a nice UI
- **[swagger_yard-rails](https://github.com/livingsocial/swagger_yard-rails)**: Seems abandoned, but serves as inspiration
- **[Rswag](https://github.com/rswag/rswag)**: Not automatic, depends on RSpec; Many developers now use Minitest as it's the default test framework
- **[grape-swagger](https://github.com/ruby-grape/grape-swagger)**: Requires Grape
- **[rspec_api_documentation](https://github.com/zipmark/rspec_api_documentation)**: Requires RSpec and a command to generate the docs
## What Sets OasRails Apart?
- **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)
## 📽️ Motivation
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](https://stackoverflow.com/questions/71947018/is-there-a-way-to-generate-an-interactive-documentation-for-rails-apis) 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](https://yardoc.org/) tags.
## Documentation
For see how to install, configure and use OasRails please refere to the [OasRailsBook](http://a-chacon.com/oas_rails)
## Contributing
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.
1. Fork the Project
2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the Branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## License
The gem is available as open source under the terms of the [GPL-3.0](https://www.gnu.org/licenses/gpl-3.0.en.html#license-text).