> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apivalk.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Request

> The `ApivalkRequestDocumentation` class is the primary container for defining the input contract of an API endpoint. It is returned by the static `getDocumentation()` method on your request class.

## Purpose

It allows you to specify exactly what data your endpoint expects, where it should be located (Body, Query, or Path), and what validation rules apply to it. This information is then used by the framework for:

1. **Automatic Validation**: via `RequestValidationMiddleware`.
2. **IDE Autocompletion**: via `DocBlockGenerator`.
3. **OpenAPI Export**: via `OpenAPIGenerator`.

## Base vs. Runtime Documentation

Apivalk distinguishes between two forms of request documentation:

* **Base documentation** — returned by the static `AbstractApivalkRequest::getDocumentation()`. Describes the request's own body/query/path properties as declared by the developer.
* **Runtime documentation** — available on the request instance via `$request->getRuntimeDocumentation()`. This is the base documentation merged with route-derived metadata (pagination query parameters, filter fields, `order_by`, available sort fields). The `RequestValidationMiddleware` validates against this merged documentation.

You normally only define the **base** documentation. The framework builds the runtime view for you via `RequestDocumentationFactory::buildRuntimeDocumentation()`.

## Structure

The class separates properties into three distinct bags:

### 1. Body Properties

Used for data sent in the request body (JSON, XML, or Form Data).

```php theme={null}
$doc->addBodyProperty(new StringProperty('username', 'The unique username'));
```

### 2. Query Properties

Used for data sent in the URL query string (e.g., `?search=term`).

```php theme={null}
$doc->addQueryProperty(new StringProperty('search', 'Search term for filtering results'));
```

### 3. Path Properties

Used for data embedded in the URL path (e.g., `/users/{id}`).

```php theme={null}
$doc->addPathProperty(new IntegerProperty('id', 'The unique identifier of the resource'));
```

## Route-Derived Properties

You do **not** need to manually add pagination, sorting, or filter query parameters. When a route declares `pagination()`, `sorting()`, or `filtering()`, the framework automatically injects the corresponding properties into the runtime documentation — and they are automatically exposed in your OpenAPI spec.

## Full Example

```php theme={null}
public static function getDocumentation(): ApivalkRequestDocumentation
{
    $doc = new ApivalkRequestDocumentation();

    $doc->addPathProperty(new StringProperty('slug', 'Post slug'));
    $doc->addQueryProperty(new BooleanProperty('include_comments', 'Whether to include comments'));
    $doc->addBodyProperty(new StringProperty('title', 'Updated title'));

    return $doc;
}
```