Request Bodies

Document request payloads with nested objects, arrays, enums, and file uploads.

Basic request body

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

The required: true on the request_body itself means the body is required. The required: true on individual properties marks them as required fields within the schema.

Nested objects

Use type: :object with a block to nest properties:

request_body required: true do
  property :email, type: :string, required: true
  property :profile, type: :object do
    property :bio, type: :string
    property :avatar_url, type: :string, format: :uri
    property :address, type: :object do
      property :street, type: :string
      property :city, type: :string
      property :zip, type: :string
    end
  end
end

You can nest objects as deep as needed.

Arrays

Use type: :array with items for simple arrays:

property :tags, type: :array, items: :string

For arrays of objects, use a block:

property :addresses, type: :array do
  property :street, type: :string
  property :city, type: :string
  property :zip, type: :string
end

Enums

Restrict values to a predefined list:

property :role, type: :string, enum: %w[customer provider admin]
property :status, type: :string, enum: %w[active inactive suspended]

File uploads

Use type: :file with content_type: "multipart/form-data":

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

type: :file maps to { type: "string", format: "binary" } in the OpenAPI spec.

Using shared schemas

Instead of defining properties inline, reference a shared schema:

request_body required: true do
  schema ref: :User
end

Optional body

For endpoints with optional request bodies:

request_body required: false do
  property :note, type: :string
end