troccoli's avatar

Absolute URL in Scribe generated response

I have an API written using Resources in Laravel. The controller return a paginated response

class SignInLogsController extends Controller
{
    /**
     * @apiResourceCollection App\Http\Resources\SignInLogResource
     * @apiResourceModel App\Models\SignInLog paginate=15
     */   public function __invoke(Request $request): ResourceCollection
    {
        return SignInLog::paginate()->toResourceCollection();
    }
}

The response has a links section which uses absolute URLs

  +"links": {#4322
    +"first": "https://hub.test/api/v1/sign-ins?page=1"
    +"last": "https://hub.test/api/v1/sign-ins?page=2"
    +"prev": null
    +"next": "https://hub.test/api/v1/sign-ins?page=2"
  }

But when I generate the documentation with Scribe, the links section has relative paths

    "links": {
        "first": "/?page=1",
        "last": "/?page=1",
        "prev": null,
        "next": null
    },

How can I make Scribe use absolute URL?

I haven't change anything in the Scribe config file, and APP_URL is correctly set in my .env file.

0 likes
2 replies
LaryAI's avatar
LaryAI
AI
4 months ago
Level 58

Scribe generates example responses by running your application in a special environment, and it uses the request context to generate URLs. By default, Scribe does not know your base URL unless you explicitly tell it. Therefore, the links in the pagination object fall back to relative URLs like /?page=1.

To get absolute URLs in Scribe's generated documentation, you need to set the base_url in your Scribe config file (config/scribe.php). This ensures Scribe is aware of your app's full URL when generating paginated links.

Solution Steps

  1. Open config/scribe.php.

  2. Find (or add) the base_url setting near the top of the config file.

  3. Set it explicitly to your app's URL. For example:

    'base_url' => env('SCRIBE_BASE_URL', env('APP_URL', 'https://hub.test')),

  4. Optionally, set SCRIBE_BASE_URL in your .env:

    SCRIBE_BASE_URL=https://hub.test

  5. Regenerate Scribe documentation:

    php artisan scribe:generate

Why is This Necessary?

Scribe doesn't always have access to your real request context, so you need to tell it what base URL to use. The APP_URL is not always respected unless it’s passed via SCRIBE_BASE_URL or directly in the config.

After this change, the links in your documented response will show absolute URLs as expected (e.g., https://hub.test/api/v1/sign-ins?page=1).

Summary:
Set the base_url option in config/scribe.php (or use SCRIBE_BASE_URL via .env) and then regenerate your docs. This will make Scribe output absolute URLs in paginated response examples.

Please or to participate in this conversation.