API documentation with Scramble

With Scramble (dedoc/scramble 0.13.40 or later) installed, the package documents the query parameters of the definitions API. Nothing has to be registered.

What is documented

An action is documented when it calls UserQuery::for(...) or Query::fromDefinition(new UserQuery(...)):

• fields[<key>] for the root type, every nested definition type, every morphTo model type and every relation without a definition, with the allowed fields;
• include with every include name, aggregates included;
• filter[<name>] typed by the filter (integer, number, boolean, date, date-time, enum values) with its default, and filter[<name>][<operator>] for every other allowed operator;
• sort with every name in both directions and the default sorts;
• page and per_page with the maximum page size, when the definition paginates;
• the 422 response of InvalidQueryParameters.

The names and the delimiter come from the query-builder config. When the action returns a JsonApiResource, these parameters replace the include and fields[...] that Scramble derives from the resource.

Queries built elsewhere

When the query is built in a service or a repository, name the definition on the action:

use MyProgs\QueryBuilder\Scramble\DocumentsQuery;

#[DocumentsQuery(UserQuery::class)]
public function index(UserService $users)
{
    return $users->list();
}

What is not documented

• a one-off Query::for(User::class) without a definition class;
• fields, filters or sorts chained after UserQuery::for();
• the spatie-compatible QueryBuilder.

A definition that cannot be built (an unknown relation, for example) is reported among the Scramble diagnostics, and the route is documented without these parameters.

Several APIs

APIs registered with Scramble::registerApi() get the parameters too. For an API configured from scratch, call QueryBuilderScramble::register(Scramble::configure('v2')). To turn the documentation off, call QueryBuilderScramble::disable() in a service provider.