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

Property options

Any property accepts these OpenAPI 3.0.3 options, in responses, request bodies, and shared schemas alike:

response 200, "User found" do
  property :id,       type: :integer, read_only: true     # readOnly
  property :password, type: :string,  write_only: true    # writeOnly
  property :role,     type: :string,  default: "member"   # default
  property :nickname, type: :string,  nullable: true       # nullable
  property :active,   type: :boolean, default: false       # falsy defaults are kept
end

They map to readOnly, writeOnly, default, and nullable in the generated spec.

Response headers

Document the headers a response returns with header inside a response block:

response 200, "Users retrieved" do
  header "X-Total-Count", type: :integer, description: "Total users available"
  header "X-RateLimit-Remaining", type: :integer, description: "Requests left in the window"

  property :users, type: :array do
    property :id, type: :integer
  end
end