FeaturesHow It WorksStoryChangelog
GitHub ↗Docs
Open Source · Made for Rails
v0.4.0

Docs suck.
Well, used to.

Write OpenAPI docs where you write code. Generate them with AI. Then explore your Rails system as a living architecture map.

$ gem "docit"
app/controllers/users_controller.rb 
# app/controllers/users_controller.rb

class UsersController < ApplicationController
  doc_for :index do
    summary "List all users"
    tags "Users"
    response 200, "Users retrieved"
  end

  def index
  end
end
▎
0
Config Needed
Works out of the box
2
Doc UIs
Scalar + Swagger
1
Command Setup
rails g docit:install
3
Ways to Write Docs
Inline · Doc files · AI

// FEATURES

Everything you need to ship docs and understand systems

Document endpoints, generate specs, and map how your Rails app fits together.

users_controller.rb
doc_for do
operation :index
summary "List all users"
tag "Users"
response 200, "Success"
end

Clean DSL

Write doc_for blocks directly in your controllers. Readable. Maintainable. No ceremony.

Terminal
$ rails g docit:install
create config/initializers/docit.rb
create app/docs/
✓ Done in 0.3s

One Command Setup

rails g docit:install. That's the whole getting started guide.

AI Auto-Docs

Point it at your routes. Your AI of choice generates the full spec. Review and ship.

📁 app/
📁 controllers/
users_controller.rb ← clean
📁 docs/
users_doc.rb
auth_doc.rb
orders_doc.rb

Separate Doc Files

Keep your controllers clean. Move docs to dedicated files with use_docs. Scales to thousands of endpoints.

Auth Schemes File Uploads Enums Nested Objects $ref Schemas Callbacks

Full OpenAPI 3.0.3

Auth schemes, file uploads, enums, nested objects, shared schemas via $ref. The full spec. No shortcuts.

Scalar
Scalar UI
Swagger
Swagger UI

Docs + System Map

Scalar for modern API docs, Swagger for the classic flow, and System Map for architecture diagrams.

// HOW IT WORKS

Four steps. That's it.

Install, document, browse — and now, see how it all connects.

01
Install

One command setup

Add the gem to your Gemfile, run the install generator, and choose your documentation style — AI-powered, scaffold, or manual.

$ rails g docit:install

create config/initializers/docit.rb

inject config/routes.rb

? Choose your setup: ai / scaffold / manual

users_controller.rb 
doc_for :index do
  summary "List all users"
  tags "Users"
  response 200, "Users retrieved"
end
02
Document

Write docs where you write code

Use the DSL right in your controller, create standalone doc files, or let AI generate everything from your routes and models.

03
Browse

Interactive docs, instantly

Visit /api-docs and get a beautiful, searchable API reference your team will actually use.

localhost:3000/api-docs
Scalar API docs UI
localhost:3000/api-docs/system
≡ Doc
→ Route GET
› index /users
◇ UsersController
▦ User
AI Explain flow
04
Map

See your system in motion

An interactive architecture diagram of your Rails app. Routes, controllers, models, and services — connected. Use AI Explain to understand any flow, written so even a new teammate can follow along.

Documented Undocumented AI selected

// SEE IT IN ACTION

Three ways to document. One gem.

Use whichever fits your workflow. Mix them across controllers.

users_controller.rb
localhost:3000/api-docs
Scalar API Reference UI Swagger API Reference UI

// HOW IT COMPARES

You've tried the alternatives.

Here's why they didn't stick — and what Docit does differently.

rswag ✗ Docs locked behind test specs

Requires writing RSpec request specs for every endpoint just to generate documentation. Your docs break when your tests break.

✓

Docit: Write docs in your controller or let AI generate them. No tests needed.

grape-swagger ✗ Only works with Grape

Need to rewrite your controllers using the Grape framework. If you're on standard Rails controllers, you're out of luck.

✓

Docit: Works with ActionController::API and ActionController::Base out of the box.

apipie ✗ No OpenAPI, no modern UI

Generates its own custom format — not OpenAPI 3.0. No Swagger UI, no Scalar, no ecosystem compatibility.

✓

Docit: Full OpenAPI 3.0.3 spec with Scalar and Swagger UI built in.

Manual YAML ✗ Drifts from your code instantly

Maintaining a separate YAML file means your docs are always one deploy behind. Nobody updates it. Nobody trusts it.

✓

Docit: Docs live next to your code. They ship together or not at all.

// THE ORIGIN STORY

Why Docit exists

In Python, API documentation is practically free. FastAPI generates it from type hints. Django REST gets you there with a decorator.

In Rails, that story didn't exist yet. The existing tools are solid, but they each ask for something extra: a test suite, a different framework, a separate DSL. For many teams, the friction was just high enough that docs never got written.

Rails deserved the same effortless documentation story. That's the gap.

So I built Docit. Inspired by what makes documentation effortless in other ecosystems: write docs where you write code, or generate them from what's already there.

No new framework to adopt. No test suite to maintain alongside it. Just your existing Rails controllers and a DSL that stays out of your way.

Documentation that lives with your code and ships when you ship.

If you've ever inherited a codebase where the API docs were "coming soon" for two years, or stared at an endpoint wondering "what does this actually return?", this gem is for you.

// FAQ

Common questions

Why not rswag?

Rswag requires you to write RSpec request specs to generate docs. That means your documentation is coupled to your test suite. Docit lets you write docs directly in your controllers or in separate files — no tests required.

How does AI auto-documentation work?

Run rails docit:autodoc and Docit analyzes your routes and controller actions, then sends them to your configured AI provider (OpenAI, Anthropic, or Groq) to generate doc files. You review, edit if needed, and ship.

Does it work with Rails 7 and 8?

Yes. Docit supports Rails 7.0+ and Rails 8. It hooks into standard ActionController — no engine-specific dependencies.

Can I customize the docs UI?

You can switch between Scalar and Swagger UI with one config line. Both support custom themes, logos, and auth configuration. You can also serve the raw JSON spec and use any OpenAPI-compatible viewer.

Read the full docs

// CHANGELOG

What's new

v0.4.0 Latest Apr 18, 2026
  • Added operation_id DSL method for custom operationId per endpoint
  • Added Auto-generated operationId for every endpoint
  • Added config.license, config.contact, config.terms_of_service options
  • Changed Renamed swagger_doc DSL to doc_for (backward-compatible alias kept)
  • Fixed TagInjector crash when initializer_path is nil
  • Fixed Removed broken --dry-run CLI flag (use DRY_RUN=1 env var)
v0.3.1 Apr 17, 2026
  • Fixed gem packaging issue with missing file
View full changelog on GitHub

Ready to ship docs
that don't suck?

One gem. One command. Beautiful API documentation for the Rails app you already have.

Let's GO!!!
$ gem "docit"