Docit

Decorator-style API documentation for Ruby on Rails. Write OpenAPI 3.0.3 docs with clean controller DSL macros, separate doc modules, or AI-assisted scaffolding for undocumented endpoints.

Scalar (default)

Swagger

Full documentation: docitruby.dev/docs

Installation

Add Docit to your Gemfile:

gem "docit"

Then run:

bundle install
rails generate docit:install

The install generator does everything in one step:

1. Creates config/initializers/docit.rb with default settings
2. Mounts the documentation engine at /api-docs in your routes
3. Asks how you'd like to set up your docs:
   • AI automatic docs — configure an AI provider, then Docit scans your routes and generates complete documentation for every endpoint
   • Manual docs — Docit scans your routes and creates scaffolded doc files with TODO placeholders, injects use_docs into controllers, and lets you fill in the details
   • Skip — just install the base config and set up docs later

Visit /api-docs to see your interactive API documentation (Scalar by default, Swagger UI also available at /api-docs/swagger).

Configuration

Edit config/initializers/docit.rb:

Docit.configure do |config|
  config.title       = "My API"
  config.version     = "1.0.0"
  config.description = "Backend API documentation"
  config.default_ui  = :scalar    # :scalar (default) or :swagger

  config.auth :bearer              # Bearer token (JWT)
  config.tag "Users", description: "User account management"
  config.server "https://api.example.com", description: "Production"
end

See the full configuration reference for all options including license, contact, terms_of_service, multiple auth schemes, and server URLs.

Quick Start

Docit supports two styles. Choose whichever fits your project or mix both.

Style 1: Inline (simple APIs)

Add doc_for blocks directly in your controller:

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

  def index
    # your code
  end
end

Upgrading? The previous swagger_doc method still works as an alias for doc_for, so existing code won't break.

Style 2: Separate doc files (recommended for larger APIs)

Keep controllers clean by defining docs in dedicated files:

# app/docs/api/v1/users_docs.rb
module Api::V1::UsersDocs
  extend Docit::DocFile

  doc :index do
    summary "List all users"
    tags "Users"

    response 200, "Users retrieved" do
      property :users, type: :array, items: :object do
        property :id, type: :integer, example: 1
        property :email, type: :string, example: "user@example.com"
      end
    end
  end
end

# app/controllers/api/v1/users_controller.rb
class Api::V1::UsersController < ApplicationController
  use_docs Api::V1::UsersDocs

  def index
    # pure business logic
  end
end

See the full DSL reference for request bodies, path parameters, enums, security, nested objects, file uploads, shared schemas, and more.

AI Documentation

Docit can generate complete API documentation using AI. Works with OpenAI, Anthropic, or Groq (free tier available).

When you run rails generate docit:install and choose AI automatic docs, everything is set up automatically — provider configuration, doc generation, controller wiring, and tag injection.

# Or set up AI docs separately:
rails generate docit:ai_setup
rails docit:autodoc

# Preview without writing files:
DRY_RUN=1 rails docit:autodoc

See the full AI documentation guide for provider details, safety considerations, and standalone commands.

Documentation UIs

Path	UI	Notes
/api-docs	Default (Scalar)	Configurable via config.default_ui
/api-docs/scalar	Scalar API Reference	Modern UI with API client, dark mode
/api-docs/swagger	Swagger UI	Classic OpenAPI explorer
/api-docs/spec	Raw JSON	OpenAPI 3.0.3 spec

How It Works

1. doc_for registers an Operation for each controller action in a global Registry
2. When someone visits /api-docs/spec, Docit's SchemaGenerator combines all registered operations with your Rails routes (via RouteInspector) to produce an OpenAPI 3.0.3 JSON document
3. The Engine serves the configured documentation UI at /api-docs, pointing it at the generated spec

Development

git clone https://github.com/S13G/docit.git
cd docit
bundle install
bundle exec rspec

Contributing

Bug reports and pull requests are welcome on GitHub.

License

MIT