description: Full annotated reference for every option in config/apiable.php.

Configuration

After publishing the configuration file with:

php artisan vendor:publish --provider="OpenSoutheners\LaravelApiable\ServiceProvider"

you will find config/apiable.php in your application. This page documents every available option.

resource_type_map

Maps Eloquent model class names to JSON:API type strings. Every model you intend to expose through JSON:API responses should have an entry here.

'resource_type_map' => [
    App\Models\Post::class => 'post',
    App\Models\User::class => 'user',
    App\Models\Tag::class  => 'tag',
],

If a model is omitted from the map, the package falls back to a snake_case version of the class basename (e.g. BlogPost → blog_post).

{% hint style="info" %} You can also register the map programmatically via Apiable::modelResourceTypeMap(). See the Installation page for details. {% endhint %}

requests

Options that govern how incoming query parameters are interpreted.

requests.validate_params

When true, query parameters sent by the client (filters, sorts, includes, etc.) are validated against the allowed definitions you declare on your JsonApiResponse. Requests containing unknown or disallowed parameters will be rejected with a validation error rather than silently ignored.

'requests' => [
    'validate_params' => true,
],

requests.filters.default_operator

The comparison operator applied when an AllowedFilter is created without an explicit operator. Available constants on AllowedFilter:

'requests' => [
    'filters' => [
        'default_operator' => \OpenSoutheners\LaravelApiable\Http\AllowedFilter::EXACT,
    ],
],

requests.filters.enforce_scoped_names

When true, scope-based filters must be declared and sent with a _scoped suffix (e.g. active_scoped instead of active). This can help disambiguate filter names from attribute names in large APIs.

'requests' => [
    'filters' => [
        'enforce_scoped_names' => true,
    ],
],

requests.sorts.default_direction

The sort direction applied when an AllowedSort is created without an explicit direction. Available constants on AllowedSort:

'requests' => [
    'sorts' => [
        'default_direction' => \OpenSoutheners\LaravelApiable\Http\AllowedSort::ASCENDANT,
    ],
],

responses

Options that control the shape and behavior of JSON:API responses.

responses.formatting.type

The default response Content-Type header. Changing this value affects how responses are formatted when no Accept header is present, or when responses.formatting.force is true.

'responses' => [
    'formatting' => [
        'type' => 'application/vnd.api+json',
    ],
],

responses.formatting.force

When true, every response uses the format defined in responses.formatting.type, regardless of the Accept header sent by the client. Useful when serving Inertia.js applications or other clients that do not negotiate content type.

{% hint style="warning" %} Enabling force means the package will never return a 406 Not Acceptable response, even when a client explicitly requests an unsupported format. Only enable this if all your consumers accept the configured format. {% endhint %}

'responses' => [
    'formatting' => [
        'force' => true,
    ],
],

You can also enable forcing programmatically for a single request without touching the config file:

use OpenSoutheners\LaravelApiable\Support\Apiable;

Apiable::forceResponseFormatting();

// Or force a specific format:
Apiable::forceResponseFormatting('application/json');

responses.normalize_relations

When true, relationship names in JSON:API responses are converted to snake_case. For example, a relation named authorProfile would appear as author_profile in the response.

'responses' => [
    'normalize_relations' => true,
],

responses.include_allowed

When true, the response meta object includes a list of the filters, sorts, and includes that are permitted for the current endpoint. This is useful during development or for self-documenting APIs.

'responses' => [
    'include_allowed' => true,
],

responses.pagination.default_size

The number of items returned per page when the client does not specify a page[size] parameter.

'responses' => [
    'pagination' => [
        'default_size' => 25,
    ],
],

responses.viewable

When true, the ViewQueryable scope is automatically applied to queries. This scope restricts results to resources the authenticated user is permitted to view. Disable it globally here, or override it per response using the JsonApiResponse API.

'responses' => [
    'viewable' => false,
],

responses.include_ids_on_attributes

When true, foreign key columns (fields ending with _id) are included in the resource attributes object of the JSON:API response. By default these are suppressed because JSON:API expresses relationships through relationships links rather than raw foreign key values.

'responses' => [
    'include_ids_on_attributes' => true,
],

documentation

Options for the apiable:docs Artisan command, which generates API documentation from your routes.

For the full reference on these settings, see the Documentation Generator section.

'documentation' => [
    'output_path' => null, // defaults to storage_path('exports/apiable') at runtime

    'default_format' => 'markdown', // markdown | postman | openapi

    'default_stub' => 'protocol', // protocol | plain (markdown only)

    'excluded_routes' => [
        '_debugbar/*',
        '_ignition/*',
        'nova-api/*',
        'nova/*',
        'nova',
        'telescope*',
        'horizon*',
    ],

    'auth' => [
        'detect_middleware' => true,

        'middleware_map' => [
            'auth:sanctum' => 'bearer',
            'auth:api'     => 'bearer',
            'auth.basic'   => 'basic',
        ],
    ],
],