Spatie JSON API Paginate

Activates automatically when spatie/laravel-json-api-paginate is installed. It documents the JSON:API-style pagination parameters your list endpoints accept when they paginate with jsonPaginate().

What it documents

Where Laravel’s paginate() reads page and per_page, the package’s jsonPaginate() reads the bracketed JSON:API form. Docuccino detects the terminal — several method calls deep, the same way it traces Query Builder chains — and adds the matching query parameters:

• page[number] — the page to return.
• page[size] — items per page, defaulting to your configured default_size and capped at max_results.
• page[cursor] — instead of page[number], when the package is configured for cursor pagination.

Your code

app/Http/Controllers/OrderController.php

public function index(): AnonymousResourceCollection
{
    $orders = Order::query()
        ->where('status', 'open')
        ->jsonPaginate();

    return OrderResource::collection($orders);
}

Generated OpenAPI

"parameters": [
  { "name": "page[number]", "in": "query", "required": false, "description": "Page number.",
    "schema": { "type": "integer", "default": 1, "minimum": 1 } },
  { "name": "page[size]", "in": "query", "required": false,
    "description": "Number of results per page.",
    "schema": { "type": "integer", "default": 30, "minimum": 1, "maximum": 30 } }
]

page[size] carries both bounds, so a client knows the ceiling before it hits it: default is the package’s default_size and maximum is max_results (both 30 out of the box).

The response envelope

When the action returns a resource collection, the 200 body is also wrapped in the { data, links, meta } paginator envelope for your configured mode:

Config	Envelope
default	Length-aware — links has first/last/prev/next; meta carries current_page, last_page, per_page, total, from, to, path
use_simple_pagination	Simple — no last link, and meta drops last_page and total (a simple paginator never counts the set)
use_cursor_pagination	Cursor — meta carries next_cursor / prev_cursor instead of counters, and page[cursor] replaces page[number]

jsonPaginate() returns a standard Laravel paginator, so this is Laravel’s own resource envelope — identical to what paginate() produces. The mode comes from the package’s config rather than the method name, because jsonPaginate() is the terminal in all three cases.

An action that returns something other than a resource collection still gets the query parameters; only the envelope needs a collection to wrap.

Respecting your config

Every name and size is read from the package’s own config/json-api-paginate.php, so the documented parameters always match the requests your app actually accepts:

Config key	Default	Effect on the docs
pagination_parameter	page	The bracket prefix — page[number] becomes e.g. cursor[number]
number_parameter	number	The page-number member name
size_parameter	size	The page-size member name
cursor_parameter	cursor	The cursor member name, under cursor pagination
method_name	jsonPaginate	The terminal method Docuccino looks for while tracing
default_size	30	page[size]’s default
max_results	30	page[size]’s maximum
use_simple_pagination	false	Selects the simple envelope
use_cursor_pagination	false	Selects the cursor envelope and page[cursor]

A per-call override is picked up too — jsonPaginate($maxResults, $defaultSize) wins over the config for that endpoint, taken from the outermost call site.

If the config can’t be read, Docuccino documents the package defaults (page[number] / page[size], size 30) and emits a json-api-paginate.default-config info diagnostic telling you to publish it, so generic-looking parameter names are never a mystery.

Configuration

Docuccino itself has nothing to configure here. The only switch is the shared enabled opt-out, per document:

// config/docuccino.php → documents.default.integrations
'json_api_paginate' => ['enabled' => false],

See the integrations reference.