🇺🇸 I Got Tired of Stale API Documentation in Rails — So I Built `rails-api-docs`

API documentation always starts with good intentions.

At the beginning of a project, everything is in sync.

Routes match reality.

Examples are accurate.

Parameters make sense.

Responses reflect exactly what the API returns.

But as the system evolves, documentation starts falling behind.

A new route gets added.

A parameter changes.

An endpoint gains authentication.

A response receives new fields.

And before you realize it, the documentation no longer represents reality.

If you've worked with Rails APIs for long enough, you've probably experienced this.

I certainly have.

And it was exactly that frustration that led me to create rails-api-docs.

GitHub: https://github.com/jacksonpires/rails-api-docs

The idea started with a simple question

Your Rails application already knows a lot.

It knows:

• your routes
• your controllers
• your parameters
• your models
• your database schema
• your HTTP verbs

So why should documentation always start from scratch?

Why do we need to manually rewrite information that already exists inside the application?

The idea behind rails-api-docs was to leverage the knowledge Rails already has to generate the first draft of the documentation automatically.

The workflow I wanted didn't exist

I didn't want another tool where the workflow looked like this:

edit documentation
→ generate artifacts
→ rebuild
→ restart server
→ validate changes

I wanted something closer to the typical Rails development experience:

edit
→ refresh browser
→ keep working

That's where the core concept of the gem came from:

A single editable YAML file that powers both development-time documentation and production-ready documentation.

A single source of truth

The entire workflow revolves around a single file:

config/rails-api-docs.yml

This file becomes the source of truth for your documentation.

From it, the gem generates:

• live documentation during development
• request examples
• response examples
• documented schemas
• static HTML documentation for production

You update one file.

Everything else updates automatically.

How it works

First, generate the initial YAML file:

rails g rails-api-docs:init

The gem automatically inspects:

• Rails.application.routes
• controllers (via Prism AST analysis)
• ActiveRecord schema

And creates an initial documentation structure.

Then start your application:

rails server

And visit:

http://localhost:3000/rails/api-docs

Whenever you modify the YAML file, simply refresh the page.

No build step.

No frontend tooling.

No intermediate process.

Let the code write the first draft

One of the most interesting parts of this project was using Prism to analyze controllers.

For example:

params.require(:user).permit(
  :email,
  :password,
  :role
)

The gem can automatically identify these fields and use them to build the initial documentation structure.

Combined with ActiveRecord schema information, it can also infer:

• field types
• required attributes
• initial examples
• schema metadata

The goal was never to replace developers.

The goal was to eliminate repetitive work.

Let the machine handle what it can already discover.

And let humans focus on the important part: explaining the API.

Documentation updates shouldn't destroy your work

This is probably the feature that frustrated me most in existing approaches.

You generate documentation.

Spend time writing descriptions.

Add examples.

Organize sections.

Customize schemas.

Then you run the generator again.

And hope nothing gets overwritten.

rails-api-docs follows an append-only strategy.

When you add new routes to your application, simply run:

rails g rails-api-docs:update

The gem appends only new endpoints.

Everything you've written remains untouched.

That includes:

• descriptions
• examples
• tags
• authentication details
• schemas
• section organization

In practice, the documentation becomes a living document rather than a disposable artifact.

Organizing larger APIs with tags

As APIs grow, navigation becomes increasingly important.

That's why the gem supports tags:

tags:
  - auth
  - public

These tags aren't just labels.

They also become interactive filters in the generated documentation.

Clicking a tag instantly filters the navigation to show only endpoints associated with that category.

This makes large APIs significantly easier to explore.

Production should be simple

Another important goal was making deployment boring.

When you're ready to publish the documentation, simply run:

rake rails-api-docs:build

The result is:

public/api-docs.html

A single HTML file.

Everything embedded.

Inline CSS.

Inline JavaScript.

No external dependencies.

No CDN.

No Asset Pipeline.

No JavaScript runtime.

Just a static file that can be hosted almost anywhere.

I'm not trying to replace OpenAPI

There are excellent OpenAPI and Swagger-based tools available today.

They solve many problems extremely well.

The goal of rails-api-docs is not to replace that ecosystem.

The idea is different.

I wanted a solution that allows developers to:

• generate documentation from an existing Rails application
• edit everything in YAML
• preview changes instantly
• export a static HTML file
• keep documentation synchronized with minimal effort

That's the workflow I was looking for.

And since I couldn't find exactly what I wanted, I decided to build it.

Final thoughts

API documentation should be easy to create and easy to maintain.

In my experience, generating the first version isn't the hard part.

Keeping it updated over time is.

rails-api-docs was created to reduce that friction.

By inspecting the application to generate a starting point.

By preserving your customizations over time.

And by providing an extremely fast feedback loop during development.

If you'd like to try it out:

⭐ https://github.com/jacksonpires/rails-api-docs

Feedback, suggestions, and contributions are always welcome.