API Reference

The api-reference package renders an OpenAPI 3.x document as a browsable API reference — tag-grouped navigation, per-operation parameter and schema trees, generated cURL and JavaScript snippets, a copy-as-Markdown button, and a request playground that executes real requests from the browser. It pairs naturally with Spectacular, which generates OpenAPI documents from a Laravel application, but renders any valid document.

Demo

The component below is live — browse the operations, inspect schemas, and switch snippet languages.

Execute has no backend here

The playground’s Execute button sends a real request from your browser, but this demo’s server (https://api.example.com) does not exist, so executing only shows how a failed request is surfaced in the response panel. Against a real API the response renders in the same panel.

Installation

composer require lattice-php/api-reference

The package ships its React renderer as source, and the lattice() Vite plugin compiles it into your app’s bundle via virtual:lattice/plugins (see Component packages). The PHP component is picked up by Lattice’s discovery automatically.

The component styles itself with Tailwind utilities, so add the package’s stylesheet to your Tailwind entry after the Lattice import — its @source directive makes your build scan the package’s components:

@import "@lattice-php/lattice/css";
@import "@lattice-php/api-reference/css";

Note

There is no npm package — Composer is the only install. No-build apps get the precompiled module via php artisan lattice:assets, but package stylesheets are not processed for standalone apps yet, so the reference currently renders unstyled there.

Usage

Pass a decoded OpenAPI document to the component on any page. With Spectacular installed, Scramble’s generator produces the document — cache it rather than regenerating per request:

use Dedoc\Scramble\Generator;
use Illuminate\Support\Facades\Cache;
use Lattice\ApiReference\ApiReference;
use Lattice\Core\Attributes\AsPage;
use Lattice\Http\Page;
use Lattice\Ui\PageSchema;

#[AsPage(route: 'docs', name: 'docs', middleware: ['auth'])]
final class ApiDocsPage extends Page
{
    public function render(PageSchema $schema, Generator $generator): PageSchema
    {
        $document = Cache::rememberForever(
            'openapi.document',
            fn (): array => $generator(),
        );

        return $schema->schema([ApiReference::make()->spec($document)]);
    }
}

Alternatively ->url('/openapi.json') makes the browser fetch the document from a URL instead of embedding it in the page props.

Scoping and presentation

ApiReference::make()
    ->spec($document)
    ->tag(['Users', 'Roles'])          // only these navigation groups
    ->defaultOperation('users.index')  // initial selection
    ->title('Acme API')                // overrides info.title
    ->hideHeader()                     // drop the title/version header
    ->hideBaseUrl()                    // drop the server picker
    ->expandDepth(3)                   // schema tree levels expanded by default
    ->twoColumnBreakpoint(Breakpoint::Xl);

->operation('users.show') pins the reference to a single operation with no navigation — useful for embedding one endpoint’s documentation inside another page.

The selected operation is mirrored to the URL hash, so operation links deep-link and survive reloads.

Request playground

Every operation carries a playground: path, query, and header parameters render as typed inputs (enum parameters become selects), JSON request bodies get an editor pre-filled with an example derived from the schema, and Execute sends the request from the browser against the server selected in the picker — responses stream into a live panel with status and headers.

ApiReference::make()
    ->spec($document)
    ->token($apiToken);

->token() pre-fills Authorization: Bearer for operations whose security scheme accepts a bearer token. Requests are plain browser fetch calls, so the API must be same-origin or send CORS headers for the reference’s origin.