--- title: "Documenting Your Rails API Shouldn’t Be Painful (Rails + OasRails)" description: "Learn how to generate OpenAPI documentation for your Rails API using OasRails." canonicalUrl: "https://zuplo.com/blog/2025/05/15/documenting-ruby-on-rails-api" pageType: "blog" date: "2025-05-15" authors: "andres" tags: "Ruby, API Tooling, Tutorial" image: "https://cdn.zuplo.com/cdn-cgi/image/fit=crop,width=1200,height=630/www/media/posts/2025-05-15-documenting-ruby-on-rails-api/image.png" --- > This article is written by [Andrés](https://github.com/a-chacon), creator of > [`oas_rails`](https://github.com/a-chacon/oas_rails). All opinions expressed > are their own. **Ruby on Rails** is an amazing framework for developing fast, stable, and scalable web applications. Just think about platforms like **GitLab**, **Shopify**, and **Mastodon**, which run **on Rails**. And just as it’s great for building monoliths, it’s also perfect for **API-only** applications—or even both at the same time. But when you have your API with **Ruby on Rails**, a key need arises: **documenting it**. For me, this is one of the most important parts. In a web application, you can test its interface experimentally, but what about an API? If it doesn’t have **clear documentation** about routes, HTTP methods, parameters, request bodies, or authentication, it won’t be very useful. Even if it’s the best API out there, it will be a headache for developers or AI trying to integrate it. ### **Options for Documenting Your API** You have two paths: 1. **External solutions** like **Postman**, **Hoppscotch**, or **Insomnia** (which I used for a long time). 2. **Rails-integrated solutions**, such as: - **[ApiPie](https://github.com/Apipie/apipie-rails)** - **[swagger_yard-rails](https://github.com/livingsocial/swagger_yard-rails)** - **[Rswag](https://github.com/rswag/rswag)** - **[grape-swagger](https://github.com/ruby-grape/grape-swagger)** - **[rspec_api_documentation](https://github.com/zipmark/rspec_api_documentation)** The problem is that none of these met my expectations. External tools, on one hand, make you dependent on an additional application—both for documenting and for the team integrating the API to visualize it. On the other hand, the integrated tools I found are often **outdated**, generate old versions of OpenAPI/Swagger, or require learning a **DSL** or specific frameworks like **RSpec** or **Grape**. And what if you’re testing your API with MiniTest or already have it built with pure Rails? Given this landscape, I created my own solution: **OasRails**. Inspired by these needs and also a bit influenced by FastAPI, which I had the chance to try out. ## **OasRails** **OasRails** is a **Rails engine** that generates an **OAS v3.1** document from your application’s routes. It examines the source code and parses method comments for YARD tags to generate comprehensive documentation, which is then displayed using **[RapiDoc](https://rapidocweb.com/)**. All of this **without external frameworks** and with minimal effort—something that can even be assisted by AI, as you’ll see later. ### **Key Features** 1. **Dynamic**: Documentation is generated on-demand, not pre-built. 2. **Automatic**: Extracts information from the code, such as route names, possible responses, and tags. 3. **Easy to Use**: Just comment your code—no **RSpec**, **DSL**, or **Grape** required. 4. **Interactive**: Thanks to **RapiDoc**, the engine delivers the OAS in a modern, clean interface. ### **How to Use It** 1. **Installation**: Follow the steps in the [documentation](https://a-chacon.com/oas_rails/installation.html). 2. **Visit** `localhost:8080/docs` to see the generated documentation. 3. **Document Your Endpoints** with YARD tags. The tags are predefined by OasRails; you can see the full list [here](https://a-chacon.com/oas_rails/tags/index.html). #### Documenting an Endpoint This is the most important step. To complete the documentation for one of your endpoints, you currently have two ways to do it: at the class level or the method level. The first is for applying general documentation to all methods in the class, while the second is specific to each method. An example of a tag that works well at the class level is `@tags`, which, as the name suggests, helps organize endpoints in the final documentation. Its usage in code would look like this: ```ruby # @tags Manage Users, Admin class UsersController < ApplicationController def index; end def create; end ... end ``` On the other hand, for specific documentation like parameters (`@parameter`) or responses (`@response`), it would look like this: ```ruby class UsersController < ApplicationController before_action :set_user, only: %i[show update destroy] # @summary Returns a list of Users. # @parameter offset(query) [Integer] Pagination offset (default: 25 items). # @parameter status(query) [Array] Filter by status (e.g., status[]=inactive). # @parameter X-front(header) [String] Header for front identification. # @response List of users(200) [Array] def index @users = User.all end end ``` It’s that simple. Refresh the documentation page, and you’ll see the changes you make. Another important aspect is security: often, you won’t want this documentation to be accessible to just anyone. OasRails also offers [a couple of solutions for this](https://a-chacon.com/oas_rails/configuration/securing.html). RapiDoc might not be the best fit for you either. It’s the best solution I found, but it might not work for everyone. In that case, no problem—OasRails generates an OAS v3.1 (`localhost:8080/docs.json` to view the content) that you can deploy in any other interface, or even import into Postman if needed. Here’s a demo where you can see OasRails in action. It’s simple but scales if you need it to: 🔗 **[Open Demo App](https://paso.fly.dev/api/docs)** 👤 **Username**: `oasrails` 🔑 **Password**: `oasrails` ### **AI-Assisted Documentation** To make the task even easier, I added **llms.txt** files to the OasRails ebook. These are standards for creating documentation that’s easy for **AI** to read and use as a knowledge source. - **[llms.txt](https://a-chacon.com/oas_rails/llms.txt)**: The basics about OasRails. (Doesn’t work well yet; the documentation fits perfectly in llms-full.txt, so I recommend using that one.) - **[llms-full.txt](https://a-chacon.com/oas_rails/llms-full.txt)**: The recommended option, with full details. #### **Example of AI Usage** You can ask questions like: - _"How to document JWT authentication in OasRails?"_ - _"Add examples of request body for the create method."_ - _"Document the endpoint ... as much as possible."_ ### **The Future of OasRails** Currently, **OasRails** needs more polishing. **Stability** will be prioritized over new features. There are several areas for improvement, but the most important ones include: - Improving the reusability of responses and request bodies. - Enhancing the definition and simplifying the set of tags currently part of the engine. - Optimizing the construction and structure of the OAS. Additionally, I realized that OasRails doesn’t necessarily have to be a Rails-only solution. Eventually, it could work for other frameworks like [**Sinatra**](/learning-center/how-to-build-an-api-with-ruby-and-sinatra) or [**Rage**](/learning-center/ruby-rage-rest-api-tutorial). This is technically very viable because YARD is designed to document Ruby code independently of the framework. Indexing endpoints and deploying the documentation would be the only parts of the code that would need adaptation. **This will be a future change, accompanied by a rename of the gem.** The project was born out of my personal need, but I hope it helps others—both **Rails** veterans and newcomers alike. **All ideas and contributions are welcome!** I believe the best guide for developing new features is feedback, so I invite you to share your thoughts on the project and what could be improved in the repo. #### Don’t Forget to Star It! ⭐️ If you find **OasRails** useful, show some love by starring the repository! Your support helps the project grow and reach more developers. 🔗 **[OasRails Repository](https://github.com/a-chacon/oas_rails)** 💡 **Pro Tip**: Starring also makes it easier to track updates and contribute in the future! 🛠️ Happy coding! 📝✨