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 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). 
$doc->addBodyProperty(new StringProperty('username', 'The unique username'));

​
2. Query Properties

Used for data sent in the URL query string (e.g., ?search=term). 
$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}). 
$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

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;
}