📄 scribe.php

<?php

/**
 * Scribe OpenAPI documentation configuration.
 * Access at: /api/docs (HTML) | /api/docs.json (OpenAPI spec)
 *
 * Generate: php artisan scribe:generate
 */

return [

    'theme'         => 'default',
    'title'         => 'STP Ecommerce API v1',
    'description'   => 'REST API for the STP Multi-Vendor Ecommerce Platform. '
        . 'Supports Nepal, India, and international commerce with full cart, checkout, '
        . 'payment gateway integration, and real-time notifications.',
    'base_url'      => env('APP_URL'),
    'routes'        => [
        [
            'match' => [
                'prefixes'   => ['api/v1/*'],
                'domains'    => ['*'],
            ],
            'include' => [],
            'exclude' => [
                'api/v1/auth/register', // documented separately
            ],
        ],
    ],

    'type'          => 'static', // 'static' generates HTML | 'laravel' uses route

    'static'        => [
        'output_path' => 'public/api/docs',
    ],

    'laravel'       => [
        'add_routes'              => true,
        'docs_url'                => '/api/docs',
        'assets_directory'        => null,
        'middleware'              => [],
    ],

    'auth'          => [
        'enabled'       => true,
        'default'       => true,
        'in'            => 'bearer',
        'name'          => 'Authorization',
        'use_value'     => env('SCRIBE_AUTH_TOKEN'),
        'placeholder'   => '{YOUR_AUTH_TOKEN}',
        'extra_info'    => 'Obtain a token by calling POST /api/v1/auth/login. '
            . 'Include it as: Authorization: Bearer {token}',
    ],

    'intro_text'    => <<<'INTRO'
Welcome to the **STP Ecommerce API v1** documentation.

## Authentication
All protected endpoints require a Sanctum bearer token obtained from `POST /api/v1/auth/login`.

## Response Format
All responses follow a consistent envelope:

**Success:**
```json
{
  "data": {},
  "meta": { "api_version": "v1", "timestamp": "..." }
}
```

**Error:**
```json
{
  "errors": [{ "code": "...", "message": "...", "field": "..." }],
  "meta": { "api_version": "v1", "timestamp": "..." }
}
```

## Pagination
Cursor-based pagination is used for large lists. See `meta.next_cursor` for the next page.

## Rate Limiting
- Public endpoints: 60 requests/minute per IP
- Authenticated endpoints: 300 requests/minute per user
INTRO,

    'example_languages' => ['bash', 'javascript', 'php'],

    'postman'       => [
        'enabled'     => true,
        'overrides'   => [
            'info.version' => '1.0.0',
        ],
    ],

    'openapi'       => [
        'enabled'   => true,
        'overrides' => [],
    ],

    'groups'        => [
        'default'   => 'Endpoints',
        'order'     => [
            'Authentication',
            'Products',
            'Categories',
            'Cart',
            'Checkout',
            'Orders',
            'Payments',
            'Reviews',
            'Q&A',
            'Loyalty Points',
            'Gift Cards',
            'Flash Sales',
            'Notifications',
            'Support Tickets',
            'Blog',
            'User Profile',
            'Addresses',
        ],
    ],

    'logo'          => null,
    'last_updated'  => 'last Git commit date',

    'fractal'       => [
        'serializer' => null,
    ],

    'routeMatcher'  => \Knuckles\Scribe\Matching\RouteMatcher::class,
];