Skip to main content

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.

​
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). 
$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. 
$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 for the concrete response objects.

​
Full Example

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.