> ## 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.

# Response

> The `ApivalkResponseDocumentation` class defines the structure of the data returned by an API endpoint. It is returned by the static `getDocumentation()` method on your response class.

## Purpose

It provides a formal definition of the successful response (HTTP 200/201), which is used to generate the OpenAPI specification. It ensures that the consumer of your API knows exactly what fields to expect in the JSON response.

## Key Features

### Property Definition

You add properties to the response using instances of `AbstractProperty` (e.g., `StringProperty`, `IntegerProperty`, `FloatProperty`, or reusable response objects).

```php theme={null}
$doc->addProperty(new StringProperty('id', 'The unique identifier of the resource'));
$doc->addProperty(new StringProperty('name', 'The human-readable name'));
```

### Response Description

You can set a human-readable description for the response, which will appear in the Swagger UI.

```php theme={null}
$doc->setDescription('Returns the profile of the authenticated user');
```

### Pagination Envelopes

Response pagination envelopes are produced automatically when your controller attaches a `PaginationResponseInterface` via `$response->setPaginationResponse(...)`. The `JsonRenderer` emits the `pagination` key and the OpenAPI generator adds the corresponding envelope schema — no flag needs to be set on the documentation.

See [Pagination](/http/pagination) for the concrete response objects.

## Full Example

```php theme={null}
public static function getDocumentation(): ApivalkResponseDocumentation
{
    $doc = new ApivalkResponseDocumentation();
    $doc->setDescription('Successfully retrieved the list of posts');

    $doc->addProperty(new StringProperty('title', 'The post title'));
    $doc->addProperty(new StringProperty('content', 'The post body'));
    $doc->addProperty(new StringProperty('created_at', 'ISO 8601 date'));

    return $doc;
}
```

## Tip: Use Resource Responses for CRUD

If your endpoint follows the standard CRUD shape, use the pre-built `Resource*Response` classes instead of authoring response documentation yourself — they wire the `data` envelope, pagination, and OpenAPI schema from the resource definition. See [Resource Responses](/resources/responses).