Laravel JSON API Paginate
Spatie’s Laravel JSON API Paginate is a great and simple package that adds support for JSON:API compliant query parameters for pagination.
Scramble has Laravel JSON API Paginate support as part of the Scramble PRO package. You can get Scramble PRO here: https://scramble.dedoc.co/pro. After purchasing, you will receive the license key via email.
Installation
Before installing Scramble PRO, make sure to update dedoc/scramble
to at least 0.12.23
.
Add the private repository to the list of your repositories in composer.json
"repositories": [ { "type": "composer", "url": "https://satis.dedoc.co" }],
Now, add the package to the list of your dependencies:
"require": { "dedoc/scramble-pro": "^0.7.9", "dedoc/scramble": "^0.12.23",}
And run composer update
.
When running composer update, you will be prompted to provide your credentials for the repository website. These credentials will authenticate your Composer session as having permission to download the Scramble PRO source code. To avoid manually typing these credentials, you may create a Composer auth.json file and use your license key in place of the password:
{ "http-basic": { "satis.dedoc.co": { "username": "youremail@company.com", "password": "YOUR-KEY-000000" } }}
You may quickly create an auth.json file via your terminal using the following command.
composer config http-basic.satis.dedoc.co \ youremail@company.com \ YOUR-KEY-000000
You should not commit your application’s auth.json
file into source control!
Usage
Whenever you use the jsonPaginate
method, Scramble adds page[size]
and page[number]
query parameters to the documentation.
use App\Models\Job;
class JobsController extends Controller{ public function index() { return Job::query()->jsonPaginate(); }}
If you’ve published the spatie/laravel-json-api-paginate
config and customized the JSON paginate method name or parameter names, Scramble will document that according to your configuration:
<?php
return [ // ..... other config options .....
/* * The key of the page[x] query string parameter for page number. */ 'number_parameter' => 'number', 'number_parameter' => 'num',
/* * The key of the page[x] query string parameter for page size. */ 'size_parameter' => 'size', 'size_parameter' => 'amount',
// ..... other config options .....];
You can modify the default page size by either changing the configuration parameter or by passing the number to the jsonPaginate
method. Scramble will document the correct default page size in both cases.
Cursor pagination
If you have enabled cursor pagination, Scramble will document the page[cursor]
query parameter.
<?php
return [ // ..... other config options .....
/* * The key of the page[x] query string parameter for cursor. */ 'cursor_parameter' => 'cursor',
/* * If you want to cursor pagination, set this to true. * This would override use_simple_pagination. */ 'use_cursor_pagination' => true,
// ..... other config options .....];