Documenting Your Rails API Shouldn’t Be Painful (Rails + OasRails)

This article is written by Andrés, creator of 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
   • swagger_yard-rails
   • Rswag
   • grape-swagger
   • 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. 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.
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.

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:

# @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:

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<String>] Filter by status (e.g., status[]=inactive).
  # @parameter X-front(header) [String] Header for front identification.
  # @response List of users(200) [Array<User>]
  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.

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
👤 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: 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: 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 or Rage. 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

💡 Pro Tip: Starring also makes it easier to track updates and contribute in the future! 🛠️

Happy coding! 📝✨