DSL Reference

Complete reference for every DSL method available inside doc_for and doc blocks. All methods work identically in both inline and separate doc file styles.

summary

A short, one-line description of the endpoint. Shown as the endpoint title in the UI.

summary "List all users"

description

A longer description of the endpoint. Supports plain text.

description "Returns a paginated list of all active users in the system"

tags

Assign the endpoint to one or more tag groups. Tags organize endpoints in the sidebar.

tags "Users"
tags "Users", "Admin"     # multiple tags

operation_id

Set a custom operationId for the endpoint. Useful for SDK client code generation. If not set, Docit auto-generates one from the action and controller name (e.g., index_users).

operation_id "listAllUsers"

deprecated

Mark the endpoint as deprecated. It'll appear with a strikethrough in most UIs.

deprecated

security

Declare that the endpoint requires authentication. References a scheme defined in configuration.

security :bearer_auth       # Bearer token
security :basic_auth        # HTTP Basic
security :api_key_auth      # API key

parameter

Document path, query, or header parameters.

parameter :id,
  location: :path,
  type: :integer,
  required: true,
  description: "User ID"

parameter :page,
  location: :query,
  type: :integer,
  description: "Page number"

parameter :status,
  location: :query,
  type: :string,
  enum: %w[active inactive],
  description: "Filter by status"

request_body

Document the request body. See Request Bodies for the full guide.

request_body required: true do
  property :email, type: :string, required: true, example: "user@example.com"
  property :password, type: :string, required: true, format: :password
  property :name, type: :string, example: "Jane Doe"
end

For file uploads, set the content type:

request_body required: true, content_type: "multipart/form-data" do
  property :avatar, type: :file, required: true, description: "Avatar image"
  property :caption, type: :string
end

response

Document response status codes. See Responses for the full guide.

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

response 404, "Not found" do
  property :error, type: :string, example: "Not found"
end

response 204, "Deleted"      # no body

property

Define a property inside request_body or response blocks.

schema (with $ref)

Reference a shared schema instead of defining properties inline. See Shared Schemas.

response 200, "User found" do
  schema ref: :User
end

request_body required: true do
  schema ref: :User
end

example (response examples)

Add named examples to a response:

response 200, "User found" do
  property :id, type: :integer
  property :email, type: :string

  example "admin_user",
          { id: 1, email: "admin@example.com" },
          description: "An admin user"

  example "regular_user",
          { id: 2, email: "user@example.com" },
          description: "A regular user"
end

Complete example

Putting it all together:

doc_for :create do
  summary "Create a user"
  description "Creates a new user account"
  tags "Users"
  operation_id "createUser"
  security :bearer_auth

  request_body required: true do
    property :email, type: :string, required: true, example: "user@example.com"
    property :password, type: :string, required: true, format: :password
    property :role, type: :string, enum: %w[customer admin]
    property :profile, type: :object do
      property :bio, type: :string
      property :avatar_url, type: :string, format: :uri
    end
  end

  response 201, "User created" do
    property :id, type: :integer, example: 1
    property :email, type: :string, example: "user@example.com"
  end

  response 422, "Validation failed" do
    property :errors, type: :object do
      property :email, type: :array, items: :string
    end
  end

  response 401, "Unauthorized"
end