Inline Documentation

The simplest way to document endpoints — add doc_for blocks directly in your controller.

Basic example

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

  def index
    @users = User.all
    render json: @users
  end
end

Place the doc_for block before the method it documents. Docit's DSL is automatically available in every controller — no include needed.

Documenting multiple actions

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

  doc_for :show do
    summary "Get a user"
    tags "Users"
    parameter :id, location: :path, type: :integer,
              required: true, description: "User ID"
    response 200, "User found"
    response 404, "User not found"
  end

  doc_for :create do
    summary "Create a user"
    tags "Users"

    request_body required: true do
      property :email, type: :string, required: true
      property :password, type: :string, required: true, format: :password
    end

    response 201, "User created"
    response 422, "Validation failed"
  end

  def index; end
  def show; end
  def create; end
end

Mixing with doc files

You can use use_docs for most actions and add inline doc_for for one-offs:

class Api::V1::UsersController < ApplicationController
  use_docs Api::V1::UsersDocs          # loads :index, :show, :create

  doc_for :destroy do                   # inline for this one action
    summary "Delete user"
    tags "Users"
    security :bearer_auth
    response 204, "Deleted"
    response 401, "Unauthorized"
  end

  def index; end
  def show; end
  def create; end
  def destroy; end
end

Backward compatibility

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

When to use inline docs

• Small APIs with few endpoints
• Quick prototyping
• One-off endpoints alongside use_docs

For larger APIs, consider separate doc files to keep controllers clean.