Responses

Document response status codes, properties, and named examples.

Basic responses

response 200, "Users retrieved"
response 201, "User created"
response 204, "Deleted"          # no body
response 401, "Unauthorized"
response 404, "Not found"
response 422, "Validation failed"

The first argument is the HTTP status code, the second is a description.

Response with properties

Add a block to define the response body schema:

response 200, "User found" do
  property :id, type: :integer, example: 1
  property :email, type: :string, example: "user@example.com"
  property :name, type: :string, example: "Jane Doe"
end

Nested response objects

response 200, "Success" do
  property :user, type: :object do
    property :id, type: :integer
    property :name, type: :string
    property :addresses, type: :array do
      property :street, type: :string
      property :city, type: :string
      property :zip, type: :string
    end
  end
  property :meta, type: :object do
    property :total, type: :integer
    property :page, type: :integer
  end
end

Error responses

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

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

Named examples

Add multiple named examples to a response for better documentation:

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

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

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

Named examples appear in the documentation UI as a dropdown, letting API consumers see different scenarios.

Using shared schemas

Instead of defining properties inline, reference a shared schema:

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

response 404, "Not found" do
  schema ref: :Error
end

Multiple responses per endpoint

Most endpoints should document both success and error cases:

doc_for :update do
  summary "Update a user"
  tags "Users"
  security :bearer_auth

  parameter :id, location: :path, type: :integer, required: true

  request_body required: true do
    property :name, type: :string
    property :email, type: :string
  end

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

  response 401, "Unauthorized"
  response 404, "User not found"
  response 422, "Validation failed" do
    property :errors, type: :object do
      property :email, type: :array, items: :string
    end
  end
end